@gtkx/cli 1.0.0-rc.4 → 1.1.0

package/src/deploy/settings/identity.ts

@@ -0,0 +1,133 @@
+import type { DeployConfig, DeployDeveloper } from "../types.js";
+import type { PackageManifest } from "./package-manifest.js";
+
+type IdentityRequest = {
+    applicationId: string;
+    deploy: DeployConfig;
+    manifest: PackageManifest;
+};
+
+const DEFAULT_METADATA_LICENSE = "CC0-1.0";
+const NAME_SEPARATORS = /[_-]+/;
+const NON_NAME_CHARACTERS = /[^a-z\d]+/;
+const SCOPE_PREFIX = /^@[^/]+\//;
+const BINARY_NAME_PATTERN = /^[a-z\d][a-z\d+.-]+$/;
+
+const lastSegment = (applicationId: string): string => applicationId.split(".").at(-1) ?? applicationId;
+
+const titleCase = (value: string): string =>
+    value
+        .split(NAME_SEPARATORS)
+        .filter((word) => word.length > 0)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+
+const normalizePackageName = (value: string): string =>
+    value
+        .replace(SCOPE_PREFIX, "")
+        .toLowerCase()
+        .split(NON_NAME_CHARACTERS)
+        .filter((part) => part.length > 0)
+        .join("-");
+
+const resolveBinaryName = ({ applicationId, deploy, manifest }: IdentityRequest): string => {
+    const configured = deploy.binaryName;
+    const derived = normalizePackageName(configured ?? manifest.name ?? lastSegment(applicationId));
+
+    if (!BINARY_NAME_PATTERN.test(derived)) {
+        throw new Error(
+            `Cannot use "${derived}" as a package name: it must match ${String(BINARY_NAME_PATTERN)}. ` +
+            "Set `deploy.binaryName`.",
+        );
+    }
+
+    return derived;
+};
+
+const resolveName = ({ applicationId, deploy, manifest }: IdentityRequest): string =>
+    deploy.name ?? titleCase(manifest.name?.replace(SCOPE_PREFIX, "") ?? lastSegment(applicationId));
+
+const resolveSummary = ({ deploy, manifest }: IdentityRequest): string => {
+    const summary = deploy.summary ?? manifest.description?.split("\n", 1)[0];
+
+    if (summary === undefined) {
+        throw new Error(
+            "Cannot deploy without a summary: set `deploy.summary` in gtkx.config.ts, " +
+            "or `description` in package.json.",
+        );
+    }
+
+    return summary;
+};
+
+const resolveDescription = (request: IdentityRequest): string[] => {
+    const configured = request.deploy.description;
+
+    return configured === undefined || configured.length === 0 ? [resolveSummary(request)] : configured;
+};
+
+const resolveDeveloperId = (applicationId: string): string | null => {
+    const segments = applicationId.split(".");
+
+    return segments.length > 2 ? segments.slice(0, -1).join(".") : null;
+};
+
+const resolveDeveloper = ({ applicationId, deploy, manifest }: IdentityRequest): DeployDeveloper => {
+    const name = deploy.developer?.name ?? manifest.author.name;
+
+    if (name === null) {
+        throw new Error(
+            "Cannot deploy without a developer: set `deploy.developer.name` in gtkx.config.ts, " +
+            "or `author` in package.json.",
+        );
+    }
+
+    return {
+        id: deploy.developer?.id ?? resolveDeveloperId(applicationId),
+        name,
+        email: deploy.developer?.email ?? manifest.author.email,
+    };
+};
+
+const resolveLicense = ({ deploy, manifest }: IdentityRequest): string => {
+    const license = deploy.license ?? manifest.license;
+
+    if (license === null) {
+        throw new Error(
+            "Cannot deploy without a license: set `deploy.license` in gtkx.config.ts, or `license` in package.json.",
+        );
+    }
+
+    return license;
+};
+
+const resolveVersionString = ({ deploy, manifest }: IdentityRequest): string => {
+    const version = deploy.version ?? manifest.version;
+
+    if (version === null) {
+        throw new Error(
+            "Cannot deploy without a version: set `deploy.version` in gtkx.config.ts, or `version` in package.json.",
+        );
+    }
+
+    return version;
+};
+
+const resolveCopyright = (request: IdentityRequest, developer: DeployDeveloper, year: number): string =>
+    request.deploy.copyright ?? `Copyright © ${String(year)} ${developer.name}`;
+
+const resolveMetadataLicense = ({ deploy }: IdentityRequest): string =>
+    deploy.metadataLicense ?? DEFAULT_METADATA_LICENSE;
+
+export {
+    type IdentityRequest,
+    resolveBinaryName,
+    resolveCopyright,
+    resolveDescription,
+    resolveDeveloper,
+    resolveLicense,
+    resolveMetadataLicense,
+    resolveName,
+    resolveSummary,
+    resolveVersionString,
+};

package/src/deploy/settings/index.ts

@@ -0,0 +1,189 @@
+import type { Config } from "@gtkx/config";
+import type {
+    DeployConfig,
+    DeployDesktopAction,
+    DeployDeveloper,
+    DeployRelease,
+    DeploySettings,
+    DeployVersions,
+} from "../types.js";
+import { resolveArch } from "./arch.js";
+import { resolveExecToken, resolveFileAssociations, resolveMimeTypes } from "./exec.js";
+import {
+    type IdentityRequest,
+    resolveBinaryName,
+    resolveCopyright,
+    resolveDescription,
+    resolveDeveloper,
+    resolveLicense,
+    resolveMetadataLicense,
+    resolveName,
+    resolveSummary,
+    resolveVersionString,
+} from "./identity.js";
+import { readPackageManifest } from "./package-manifest.js";
+import { resolvePaths } from "./paths.js";
+import { resolveScreenshots } from "./screenshots.js";
+import { resolveVersions } from "./version.js";
+
+type SettingsRequest = {
+    root: string;
+    config: Config;
+    outDirOverride?: string | undefined;
+    now?: Date | undefined;
+};
+
+type ResolvedCore = {
+    identity: IdentityRequest;
+    developer: DeployDeveloper;
+    versions: DeployVersions;
+    date: string;
+};
+
+type IdentitySlice = Pick<
+    DeploySettings,
+    | "applicationId" |
+    "binaryName" |
+    "copyright" |
+    "description" |
+    "developer" |
+    "genericName" |
+    "homepage" |
+    "license" |
+    "metadataLicense" |
+    "name" |
+    "summary"
+>;
+
+type MetadataSlice = Pick<
+    DeploySettings,
+    "branding" | "categories" | "contentRating" | "keywords" | "mimeTypes" | "releases" | "screenshots" | "urls"
+>;
+
+type DesktopSlice = Pick<
+    DeploySettings,
+    | "desktopActions" |
+    "desktopEntry" |
+    "execArgs" |
+    "execToken" |
+    "fileAssociations" |
+    "isDbusActivatable" |
+    "protocols"
+>;
+
+const ISO_DATE_LENGTH = 10;
+const MILLISECONDS_PER_SECOND = 1000;
+
+const reproducibleDate = (epoch: string | undefined): Date | null => {
+    if (epoch === undefined || epoch.trim().length === 0) {
+        return null;
+    }
+
+    const seconds = Number(epoch);
+
+    return Number.isFinite(seconds) ? new Date(seconds * MILLISECONDS_PER_SECOND) : null;
+};
+
+const buildDate = (now: Date): string => {
+    const stamp = reproducibleDate(process.env.SOURCE_DATE_EPOCH) ?? now;
+
+    return stamp.toISOString().slice(0, ISO_DATE_LENGTH);
+};
+
+const newestFirst = (a: DeployRelease, b: DeployRelease): number => Number(a.date < b.date) - Number(a.date > b.date);
+
+const resolveReleases = (deploy: DeployConfig, version: string, date: string): DeployRelease[] =>
+    (deploy.releases ?? [{ version, date }])
+        .map((entry) => ({
+            version: entry.version,
+            date: entry.date,
+            type: entry.type ?? null,
+            urgency: entry.urgency ?? null,
+            notes: entry.notes ?? [],
+            url: entry.url ?? null,
+        }))
+        .toSorted(newestFirst);
+
+const resolveDesktopActions = (deploy: DeployConfig): DeployDesktopAction[] =>
+    Object.entries(deploy.desktopActions ?? {}).map(([id, action]) => ({
+        id,
+        name: action.name,
+        args: action.args ?? [],
+        icon: action.icon ?? null,
+    }));
+
+const resolveLibraries = (config: Config): string[] => (Array.isArray(config.libraries) ? config.libraries : []);
+
+const identitySlice = ({ identity, developer, date }: ResolvedCore): IdentitySlice => ({
+    applicationId: identity.applicationId,
+    binaryName: resolveBinaryName(identity),
+    name: resolveName(identity),
+    genericName: identity.deploy.genericName ?? null,
+    summary: resolveSummary(identity),
+    description: resolveDescription(identity),
+    developer,
+    license: resolveLicense(identity),
+    metadataLicense: resolveMetadataLicense(identity),
+    copyright: resolveCopyright(identity, developer, new Date(date).getUTCFullYear()),
+    homepage: identity.deploy.homepage ?? identity.manifest.homepage,
+});
+
+const metadataSlice = (root: string, { identity, versions, date }: ResolvedCore): MetadataSlice => {
+    const deploy = identity.deploy;
+
+    return {
+        keywords: deploy.keywords ?? [],
+        categories: deploy.categories ?? [],
+        mimeTypes: resolveMimeTypes(deploy),
+        urls: deploy.urls ?? {},
+        screenshots: resolveScreenshots({ root, deploy }),
+        branding: deploy.branding ?? null,
+        contentRating: deploy.contentRating ?? {},
+        releases: resolveReleases(deploy, versions.packageVersion, date),
+    };
+};
+
+const desktopSlice = (deploy: DeployConfig): DesktopSlice => ({
+    execArgs: deploy.execArgs ?? [],
+    execToken: resolveExecToken(deploy),
+    fileAssociations: resolveFileAssociations(deploy),
+    protocols: deploy.protocols ?? [],
+    desktopActions: resolveDesktopActions(deploy),
+    desktopEntry: deploy.desktopEntry ?? {},
+    isDbusActivatable: deploy.isDbusActivatable ?? false,
+});
+
+const resolveCore = (request: SettingsRequest): ResolvedCore => {
+    const identity: IdentityRequest = {
+        applicationId: request.config.applicationId,
+        deploy: request.config.deploy ?? {},
+        manifest: readPackageManifest(request.root),
+    };
+
+    const versions = resolveVersions({
+        version: resolveVersionString(identity),
+        release: identity.deploy.release,
+        epoch: identity.deploy.epoch,
+    });
+
+    return { identity, developer: resolveDeveloper(identity), versions, date: buildDate(request.now ?? new Date()) };
+};
+
+const resolveDeploySettings = (request: SettingsRequest): DeploySettings => {
+    const core = resolveCore(request);
+    const deploy = core.identity.deploy;
+
+    return {
+        ...identitySlice(core),
+        ...metadataSlice(request.root, core),
+        ...desktopSlice(deploy),
+        extraFiles: deploy.extraFiles ?? {},
+        versions: core.versions,
+        arch: resolveArch(),
+        paths: resolvePaths({ root: request.root, deploy, outDirOverride: request.outDirOverride }),
+        libraries: resolveLibraries(request.config),
+        deploy,
+    };
+};
+
+export { resolveDeploySettings };

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

@@ -0,0 +1,66 @@
+import { isRecord } from "@gtkx/utils";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+type ManifestAuthor = {
+    name: string | null;
+    email: string | null;
+};
+
+type PackageManifest = {
+    name: string | null;
+    version: string | null;
+    description: string | null;
+    license: string | null;
+    homepage: string | null;
+    author: ManifestAuthor;
+};
+
+const AUTHOR_PATTERN = /^(?<name>[^<(]*)(?:\([^)]*\)\s*)?(?:<(?<email>[^>]*)>)?/;
+const EMPTY_AUTHOR: ManifestAuthor = { name: null, email: null };
+
+const optionalString = (value: unknown): string | null =>
+    typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+
+const parseAuthorString = (author: string): ManifestAuthor => {
+    const groups = AUTHOR_PATTERN.exec(author)?.groups;
+
+    return { name: optionalString(groups?.name), email: optionalString(groups?.email) };
+};
+
+const parseAuthor = (author: unknown): ManifestAuthor => {
+    if (typeof author === "string") {
+        return parseAuthorString(author);
+    }
+
+    if (!isRecord(author)) {
+        return EMPTY_AUTHOR;
+    }
+
+    return { name: optionalString(author.name), email: optionalString(author.email) };
+};
+
+const readManifestJson = (root: string): Record<string, unknown> => {
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+
+        return isRecord(parsed) ? parsed : {};
+    } catch {
+        return {};
+    }
+};
+
+const readPackageManifest = (root: string): PackageManifest => {
+    const manifest = readManifestJson(root);
+
+    return {
+        name: optionalString(manifest.name),
+        version: optionalString(manifest.version),
+        description: optionalString(manifest.description),
+        license: optionalString(manifest.license),
+        homepage: optionalString(manifest.homepage),
+        author: parseAuthor(manifest.author),
+    };
+};
+
+export { type PackageManifest, readPackageManifest };

package/src/deploy/settings/paths.ts

@@ -0,0 +1,115 @@
+import { type Stats, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import type { DeployConfig, DeployPaths } from "../types.js";
+import { resolveDataDir } from "../../internal/data-dir.js";
+import { findSchemaFiles } from "../../settings/schema.js";
+
+type PathsRequest = {
+    root: string;
+    deploy: DeployConfig;
+    outDirOverride: string | undefined;
+};
+
+type ResolvedIcons = {
+    iconsDir: string | null;
+    iconFile: string | null;
+};
+
+const DEFAULT_OUT_DIR = "build";
+const DIST_DIR = "dist";
+const ICONS_DIR = "icons";
+const LICENSE_CANDIDATES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "COPYING.md"];
+
+const isInside = (parent: string, candidate: string): boolean => {
+    const rel = relative(parent, candidate);
+
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+};
+
+const resolveOutDir = ({ root, deploy, outDirOverride }: PathsRequest): string => {
+    const configured = outDirOverride ?? deploy.outDir ?? DEFAULT_OUT_DIR;
+    const outDir = resolve(root, configured);
+
+    if (!isInside(root, outDir)) {
+        throw new Error(`Cannot use "${configured}" as the deploy output directory: it is outside ${root}`);
+    }
+
+    return outDir;
+};
+
+const getStats = (path: string): Stats | undefined => {
+    try {
+        return statSync(path, { throwIfNoEntry: false });
+    } catch {
+        return undefined;
+    }
+};
+
+const existingFile = (path: string): string | null => (getStats(path)?.isFile() === true ? path : null);
+const existingDir = (path: string): string | null => (getStats(path)?.isDirectory() === true ? path : null);
+
+const resolveLicenseFile = (root: string, configured: string | undefined): string | null => {
+    if (configured !== undefined) {
+        const path = resolve(root, configured);
+
+        if (existingFile(path) === null) {
+            throw new Error(`Cannot read the license file "${configured}": no such file under ${root}`);
+        }
+
+        return path;
+    }
+
+    return LICENSE_CANDIDATES.map((name) => existingFile(join(root, name))).find((path) => path !== null) ?? null;
+};
+
+const configuredIcons = (root: string, configured: string): ResolvedIcons => {
+    const path = resolve(root, configured);
+
+    if (!isInside(root, path)) {
+        throw new Error(`Cannot use "${configured}" as the icon path: it is outside ${root}`);
+    }
+
+    if (existingDir(path) !== null) {
+        return { iconsDir: path, iconFile: null };
+    }
+
+    if (existingFile(path) === null) {
+        throw new Error(`Cannot read the icon path "${configured}": no such file or directory under ${root}`);
+    }
+
+    return { iconsDir: null, iconFile: path };
+};
+
+const defaultIcons = (root: string, dataDir: string | null): ResolvedIcons => ({
+    iconsDir: dataDir === null ? null : existingDir(join(root, dataDir, ICONS_DIR)),
+    iconFile: null,
+});
+
+const resolveIcons = (root: string, dataDir: string | null, configured: string | undefined): ResolvedIcons =>
+    configured === undefined ? defaultIcons(root, dataDir) : configuredIcons(root, configured);
+
+const resolvePaths = (request: PathsRequest): DeployPaths => {
+    const { root, deploy } = request;
+    const outDir = resolveOutDir(request);
+    const dataDir = resolveDataDir(root);
+    const { iconsDir, iconFile } = resolveIcons(root, dataDir, deploy.icons);
+
+    return {
+        root,
+        dist: join(root, DIST_DIR),
+        outDir,
+        metadata: join(outDir, "metadata"),
+        runtime: join(outDir, "runtime"),
+        stage: join(outDir, "stage"),
+        overlay: join(outDir, "overlay"),
+        targets: join(outDir, "targets"),
+        output: join(outDir, "out"),
+        dataDir,
+        iconsDir,
+        iconFile,
+        licenseFile: resolveLicenseFile(root, deploy.licenseFile),
+        schemaFiles: dataDir === null ? [] : findSchemaFiles(join(root, dataDir)),
+    };
+};
+
+export { resolvePaths };

package/src/deploy/settings/screenshots.ts

@@ -0,0 +1,125 @@
+import type { DeployConfig, DeployScreenshot } from "../types.js";
+import { gitRemoteUrl, runGit } from "../git.js";
+
+type ScreenshotRequest = {
+    root: string;
+    deploy: DeployConfig;
+};
+
+type RemoteParts = {
+    host: string;
+    owner: string;
+    repo: string;
+};
+
+const DEFAULT_BRANCH = "main";
+const GIT_SUFFIX = ".git";
+const PORTED_HOST = /^([^/]*):\d+(?=\/|$)/;
+const SCHEME_SEPARATOR = "://";
+const TRAILING_SLASH = "/";
+
+const RAW_BASE_BY_HOST: Record<string, (owner: string, repo: string, branch: string) => string> = {
+    "github.com": (owner, repo, branch) => `https://raw.githubusercontent.com/${owner}/${repo}/${branch}`,
+    "gitlab.com": (owner, repo, branch) => `https://gitlab.com/${owner}/${repo}/-/raw/${branch}`,
+};
+
+const readRepositoryPrefix = (root: string): string =>
+    trimTrailingSlash(runGit(root, ["rev-parse", "--show-prefix"]) ?? "");
+
+const trimTrailingSlash = (value: string): string =>
+    value.endsWith(TRAILING_SLASH) ? trimTrailingSlash(value.slice(0, -1)) : value;
+
+const trimLeadingSlash = (value: string): string => {
+    const withoutDot = value.startsWith("./") ? value.slice(2) : value;
+
+    return withoutDot.startsWith(TRAILING_SLASH) ? withoutDot.slice(1) : withoutDot;
+};
+
+const afterMarker = (value: string, marker: string): string => {
+    const index = value.indexOf(marker);
+
+    return index === -1 ? value : value.slice(index + marker.length);
+};
+
+const normalizeLocation = (trimmed: string): string => {
+    const location = afterMarker(afterMarker(trimmed, SCHEME_SEPARATOR), "@");
+
+    return trimmed.includes(SCHEME_SEPARATOR) ? location.replace(PORTED_HOST, "$1") : location.replace(":", "/");
+};
+
+const parseRemote = (remote: string): RemoteParts | null => {
+    const trimmed = remote.endsWith(GIT_SUFFIX) ? remote.slice(0, -GIT_SUFFIX.length) : remote;
+    const [host, owner, repo, ...extra] = normalizeLocation(trimmed).split("/");
+
+    if (repo === undefined || extra.length > 0) {
+        return null;
+    }
+
+    return { host: host ?? "", owner: owner ?? "", repo };
+};
+
+const readDefaultBranch = (root: string): string => {
+    const head = runGit(root, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+
+    if (head === null || head.length === 0) {
+        return DEFAULT_BRANCH;
+    }
+
+    const separator = head.indexOf(TRAILING_SLASH);
+
+    return separator === -1 ? head : head.slice(separator + 1);
+};
+
+const baseForRemote = (remote: string, branch: string): string | null => {
+    const parts = parseRemote(remote);
+
+    if (parts === null) {
+        return null;
+    }
+
+    const build = RAW_BASE_BY_HOST[parts.host];
+
+    return build === undefined ? null : build(parts.owner, parts.repo, branch);
+};
+
+const resolveScreenshotBaseUrl = ({ root, deploy }: ScreenshotRequest): string | null => {
+    if (deploy.screenshotBaseUrl !== undefined) {
+        return trimTrailingSlash(deploy.screenshotBaseUrl);
+    }
+
+    const remote = gitRemoteUrl(root);
+    const base = remote === null ? null : baseForRemote(remote, readDefaultBranch(root));
+    const prefix = base === null ? "" : readRepositoryPrefix(root);
+
+    return base === null || prefix.length === 0 ? base : `${base}/${prefix}`;
+};
+
+const urlForScreenshot = (file: string, baseUrl: string | null): string => {
+    if (baseUrl === null) {
+        throw new Error(
+            `Cannot turn the screenshot "${file}" into a URL: a software center fetches screenshots over the ` +
+            "network. Set `deploy.screenshotBaseUrl`, or give the screenshot an absolute `url`.",
+        );
+    }
+
+    return `${baseUrl}/${trimLeadingSlash(file)}`;
+};
+
+const resolveScreenshots = (request: ScreenshotRequest): DeployScreenshot[] => {
+    const configured = request.deploy.screenshots ?? [];
+
+    if (configured.length === 0) {
+        return [];
+    }
+
+    const baseUrl = resolveScreenshotBaseUrl(request);
+    const defaultIndex = configured.findIndex((entry) => entry.isDefault === true);
+
+    return configured.map((entry, index) => ({
+        url: entry.url ?? urlForScreenshot(entry.file ?? "", baseUrl),
+        caption: entry.caption ?? null,
+        isDefault: index === defaultIndex,
+    }));
+};
+
+export { resolveScreenshots };

package/src/deploy/settings/starter.ts

@@ -0,0 +1,41 @@
+import type { PackageManifest } from "./package-manifest.js";
+
+const INDENT = " ".repeat(4);
+const DOCS_URL = "https://gtkx.dev/guide/deploying";
+
+const quoted = (value: string): string => JSON.stringify(value);
+
+const titleFor = (applicationId: string): string => {
+    const segment = applicationId.split(".").at(-1) ?? applicationId;
+
+    return segment.charAt(0).toUpperCase() + segment.slice(1);
+};
+
+const developerLine = (manifest: PackageManifest): string => {
+    const name = manifest.author.name ?? "Your Name";
+    const email = manifest.author.email;
+    const parts = email === null ? [`name: ${quoted(name)}`] : [`name: ${quoted(name)}`, `email: ${quoted(email)}`];
+
+    return `${INDENT.repeat(2)}developer: { ${parts.join(", ")} },`;
+};
+
+const starterBlock = (applicationId: string, manifest: PackageManifest): string =>
+    [
+        `${INDENT}deploy: {`,
+        `${INDENT.repeat(2)}name: ${quoted(manifest.name ?? titleFor(applicationId))},`,
+        `${INDENT.repeat(2)}summary: ${quoted(manifest.description ?? "What the app does, in one line")},`,
+        `${INDENT.repeat(2)}categories: ["Utility"],`,
+        developerLine(manifest),
+        `${INDENT.repeat(2)}license: ${quoted(manifest.license ?? "MIT")},`,
+        `${INDENT}},`,
+    ].join("\n");
+
+const missingDeployError = (applicationId: string, manifest: PackageManifest): Error =>
+    new Error(
+        "gtkx.config.ts: no `deploy` section, so there is nothing to package.\n" +
+        "Add this to gtkx.config.ts and adjust it:\n\n" +
+        `${starterBlock(applicationId, manifest)}\n\n` +
+        `Every value above was derived from package.json; see ${DOCS_URL}.`,
+    );
+
+export { missingDeployError };