@gtkx/cli 1.0.0 → 1.1.0

package/src/deploy/types.ts

@@ -0,0 +1,174 @@
+import type { Config } from "@gtkx/config";
+
+type DeployConfig = NonNullable<Config["deploy"]>;
+type DeployTargetName = NonNullable<DeployConfig["targets"]>[number];
+type PackageFamily = "arch" | "debian" | "fedora" | "suse" | "unknown";
+
+type DeployTool = {
+    command: string;
+    purpose: string;
+    isOptional: boolean;
+    isPresent?: () => boolean;
+};
+
+type StagedFile = {
+    rel: string;
+    abs: string;
+    mode: number;
+};
+
+type NodeRuntime = {
+    path: string;
+    version: string;
+    glibcFloor: string | null;
+    isStripped: boolean;
+};
+
+type DeployDeveloper = {
+    id: string | null;
+    name: string;
+    email: string | null;
+};
+
+type DeployScreenshot = {
+    url: string;
+    caption: string | null;
+    isDefault: boolean;
+};
+
+type DeployRelease = {
+    version: string;
+    date: string;
+    type: string | null;
+    urgency: string | null;
+    notes: string[];
+    url: string | null;
+};
+
+type DeployFileAssociation = {
+    extension: string;
+    mimeType: string;
+    description: string | null;
+};
+
+type DeployDesktopAction = {
+    id: string;
+    name: string;
+    args: string[];
+    icon: string | null;
+};
+
+type DeployVersions = {
+    upstream: string;
+    packageVersion: string;
+    debRevision: string;
+    rpmRelease: string;
+    epoch: number | null;
+};
+
+type DeployArch = {
+    deb: string;
+    rpm: string;
+    flatpak: string;
+    appimage: string;
+    node: string;
+};
+
+type DeployPaths = {
+    root: string;
+    dist: string;
+    outDir: string;
+    metadata: string;
+    runtime: string;
+    stage: string;
+    overlay: string;
+    targets: string;
+    output: string;
+    dataDir: string | null;
+    iconsDir: string | null;
+    iconFile: string | null;
+    licenseFile: string | null;
+    schemaFiles: string[];
+};
+
+type DeploySettings = {
+    applicationId: string;
+    binaryName: string;
+    name: string;
+    genericName: string | null;
+    summary: string;
+    description: string[];
+    keywords: string[];
+    categories: string[];
+    mimeTypes: string[];
+    developer: DeployDeveloper;
+    license: string;
+    metadataLicense: string;
+    copyright: string;
+    homepage: string | null;
+    urls: Record<string, string>;
+    screenshots: DeployScreenshot[];
+    branding: { light: string; dark: string } | null;
+    contentRating: Record<string, string>;
+    releases: DeployRelease[];
+    execArgs: string[];
+    execToken: string | null;
+    fileAssociations: DeployFileAssociation[];
+    protocols: string[];
+    desktopActions: DeployDesktopAction[];
+    desktopEntry: Record<string, string>;
+    isDbusActivatable: boolean;
+    extraFiles: Record<string, string>;
+    versions: DeployVersions;
+    arch: DeployArch;
+    paths: DeployPaths;
+    libraries: string[];
+    deploy: DeployConfig;
+};
+
+type DeployPayload = {
+    settings: DeploySettings;
+    node: NodeRuntime | null;
+    stage: StagedFile[];
+    overlays: Record<DeployTargetName, StagedFile[]>;
+};
+
+type DeployManifest = {
+    path: string;
+    contents: string;
+};
+
+type DeployArtifact = {
+    path: string;
+    size: number;
+};
+
+type DeployTarget = {
+    name: DeployTargetName;
+    prefix: string;
+    tools: DeployTool[];
+    render: (payload: DeployPayload) => DeployManifest[];
+    pack: (payload: DeployPayload, manifests: DeployManifest[]) => Promise<DeployArtifact[]>;
+};
+
+export type {
+    DeployArch,
+    DeployArtifact,
+    DeployConfig,
+    DeployDesktopAction,
+    DeployDeveloper,
+    DeployFileAssociation,
+    DeployManifest,
+    DeployPaths,
+    DeployPayload,
+    DeployRelease,
+    DeployScreenshot,
+    DeploySettings,
+    DeployTarget,
+    DeployTargetName,
+    DeployTool,
+    DeployVersions,
+    NodeRuntime,
+    PackageFamily,
+    StagedFile,
+};

package/src/deploy/vendored/appimagetool.ts

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import { cacheDir, downloadFile } from "../download.js";
+
+type AppimageTooling = {
+    tool: string;
+    runtime: string;
+};
+
+const APPIMAGETOOL_VERSION = "1.9.1";
+const RUNTIME_VERSION = "20251108";
+const APPIMAGETOOL_URL = `https://github.com/AppImage/appimagetool/releases/download/${APPIMAGETOOL_VERSION}`;
+const RUNTIME_URL = `https://github.com/AppImage/type2-runtime/releases/download/${RUNTIME_VERSION}`;
+const EXECUTABLE_MODE = 0o755;
+
+const APPIMAGETOOL_DIGESTS: Record<string, string> = {
+    aarch64: "f0837e7448a0c1e4e650a93bb3e85802546e60654ef287576f46c71c126a9158",
+    x86_64: "ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0",
+};
+
+const RUNTIME_DIGESTS: Record<string, string> = {
+    aarch64: "00cbdfcf917cc6c0ff6d3347d59e0ca1f7f45a6df1a428a0d6d8a78664d87444",
+    x86_64: "2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d",
+};
+
+const digestFor = (digests: Record<string, string>, arch: string, subject: string): string => {
+    const digest = digests[arch];
+
+    if (digest === undefined) {
+        throw new Error(`${subject} has no pinned build for ${arch}`);
+    }
+
+    return digest;
+};
+
+const resolveAppimageTooling = async (arch: string): Promise<AppimageTooling> => {
+    const dir = cacheDir(["appimage", `${APPIMAGETOOL_VERSION}-${RUNTIME_VERSION}`]);
+
+    const tool = await downloadFile({
+        url: `${APPIMAGETOOL_URL}/appimagetool-${arch}.AppImage`,
+        dest: join(dir, `appimagetool-${arch}`),
+        label: `appimagetool ${APPIMAGETOOL_VERSION}`,
+        sha256: digestFor(APPIMAGETOOL_DIGESTS, arch, "appimagetool"),
+        mode: EXECUTABLE_MODE,
+    });
+
+    const runtime = await downloadFile({
+        url: `${RUNTIME_URL}/runtime-${arch}`,
+        dest: join(dir, `runtime-${arch}`),
+        label: `the AppImage runtime ${RUNTIME_VERSION}`,
+        sha256: digestFor(RUNTIME_DIGESTS, arch, "the AppImage runtime"),
+        mode: EXECUTABLE_MODE,
+    });
+
+    return { tool, runtime };
+};
+
+export { resolveAppimageTooling };

package/src/deploy/vendored/nfpm.ts

@@ -0,0 +1,79 @@
+import { mkdtempSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { cacheDir, downloadFile } from "../download.js";
+
+const NFPM_VERSION = "2.47.0";
+const NFPM_BASE_URL = `https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}`;
+
+const NFPM_ASSET_ARCH: Record<string, string> = {
+    arm64: "arm64",
+    x64: "x86_64",
+};
+
+const NFPM_DIGESTS: Record<string, string> = {
+    arm64: "1c0f5f2999b9a974bfb04fdb0cc3306096de530ac5dbb25d739cc5f5219c919c",
+    x86_64: "0660ca602b2d2d2ae4781a06c692b3eeb9d437ffea05b831d76e41f4a3188783",
+};
+
+const assetArchFor = (arch: string): string => {
+    const assetArch = NFPM_ASSET_ARCH[arch];
+
+    if (assetArch === undefined) {
+        throw new Error(`nfpm has no Linux build for ${arch}`);
+    }
+
+    return assetArch;
+};
+
+const assetNameFor = (arch: string): string => `nfpm_${NFPM_VERSION}_Linux_${assetArchFor(arch)}.tar.gz`;
+
+const digestFor = (arch: string): string => {
+    const digest = NFPM_DIGESTS[assetArchFor(arch)];
+
+    if (digest === undefined) {
+        throw new Error(`nfpm ${NFPM_VERSION} has no pinned digest for ${arch}`);
+    }
+
+    return digest;
+};
+
+const extractNfpm = (archive: string, binary: string): void => {
+    const dir = mkdtempSync(`${binary}-`);
+
+    try {
+        runCliTool({ tool: "tar", args: ["-xzf", archive, "-C", dir, "nfpm"], target: assetNameFor(process.arch) });
+        renameSync(join(dir, "nfpm"), binary);
+    } finally {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 5 });
+    }
+};
+
+const downloadNfpm = async (dir: string, binary: string): Promise<string> => {
+    const assetName = assetNameFor(process.arch);
+
+    const archive = await downloadFile({
+        url: `${NFPM_BASE_URL}/${assetName}`,
+        dest: join(dir, assetName),
+        label: `nfpm ${NFPM_VERSION}`,
+        sha256: digestFor(process.arch),
+    });
+
+    extractNfpm(archive, binary);
+
+    return binary;
+};
+
+const resolveNfpm = async (): Promise<string> => {
+    const override = process.env.GTKX_NFPM;
+
+    if (override !== undefined && override.length > 0) {
+        return override;
+    }
+
+    const dir = cacheDir(["nfpm", NFPM_VERSION]);
+
+    return downloadNfpm(dir, join(dir, "nfpm"));
+};
+
+export { resolveNfpm };

package/src/dev/change-queue.ts

@@ -0,0 +1,59 @@
+import type { DevServerWatchEvent } from "./vite-dev-server.js";
+
+type WatchedChange = {
+    event: DevServerWatchEvent;
+    path: string;
+};
+
+type ChangeQueue = {
+    enqueue: (change: WatchedChange) => void;
+};
+
+type QueueState = {
+    queued: WatchedChange[];
+    isDraining: boolean;
+    run: (change: WatchedChange) => Promise<void>;
+};
+
+const isSameChange = (left: WatchedChange, right: WatchedChange): boolean =>
+    left.event === right.event && left.path === right.path;
+
+const drainQueue = async (state: QueueState): Promise<void> => {
+    state.isDraining = true;
+
+    try {
+        await Promise.resolve();
+        let change = state.queued.shift();
+
+        while (change !== undefined) {
+            await state.run(change);
+            change = state.queued.shift();
+        }
+    } finally {
+        state.isDraining = false;
+    }
+};
+
+const enqueueChange = (state: QueueState, change: WatchedChange): void => {
+    if (state.queued.some((queued) => isSameChange(queued, change))) {
+        return;
+    }
+
+    state.queued.push(change);
+
+    if (!state.isDraining) {
+        void drainQueue(state);
+    }
+};
+
+const createChangeQueue = (run: (change: WatchedChange) => Promise<void>): ChangeQueue => {
+    const state: QueueState = { queued: [], isDraining: false, run };
+
+    return {
+        enqueue: (change) => {
+            enqueueChange(state, change);
+        },
+    };
+};
+
+export { createChangeQueue, type WatchedChange };

package/src/dev/failure-tracker.ts

@@ -0,0 +1,92 @@
+type FailureTracker = {
+    isDown: () => boolean;
+    hasReported: () => boolean;
+    fail: (cause?: unknown) => void;
+    report: (cause: unknown) => void;
+    settleUnmount: (decide: () => void) => void;
+};
+
+type FailureState = {
+    isDown: boolean;
+    hasReported: boolean;
+    isUnmounting: boolean;
+    announced: WeakSet<object>;
+    announce: (cause: unknown) => void;
+    isRefreshing: () => boolean;
+};
+
+const UNMOUNT_SETTLE_MS = 0;
+
+const wasAnnounced = (state: FailureState, cause: unknown): boolean => {
+    if (typeof cause !== "object" || cause === null) {
+        return false;
+    }
+
+    if (state.announced.has(cause)) {
+        return true;
+    }
+
+    state.announced.add(cause);
+
+    return false;
+};
+
+const recordCause = (state: FailureState, cause: unknown): void => {
+    state.hasReported = true;
+
+    if (!wasAnnounced(state, cause)) {
+        state.announce(cause);
+    }
+};
+
+const failState = (state: FailureState, cause: unknown): void => {
+    state.isDown = true;
+
+    if (cause !== undefined) {
+        recordCause(state, cause);
+    }
+};
+
+const reportState = (state: FailureState, cause: unknown): void => {
+    if (state.isUnmounting || state.isRefreshing()) {
+        state.isDown = true;
+    }
+
+    recordCause(state, cause);
+};
+
+const settleUnmountState = (state: FailureState, decide: () => void): void => {
+    state.isUnmounting = true;
+
+    setTimeout(() => {
+        state.isUnmounting = false;
+        decide();
+    }, UNMOUNT_SETTLE_MS);
+};
+
+const createFailureTracker = (announce: (cause: unknown) => void, isRefreshing: () => boolean): FailureTracker => {
+    const state: FailureState = {
+        isDown: false,
+        hasReported: false,
+        isUnmounting: false,
+        announced: new WeakSet(),
+        announce,
+        isRefreshing,
+    };
+
+    return {
+        isDown: () => state.isDown,
+        hasReported: () => state.hasReported,
+        fail: (cause) => {
+            failState(state, cause);
+        },
+        report: (cause) => {
+            reportState(state, cause);
+        },
+        settleUnmount: (decide) => {
+            settleUnmountState(state, decide);
+        },
+    };
+};
+
+export { createFailureTracker, type FailureTracker };

package/src/dev/missing-import.ts

@@ -0,0 +1,32 @@
+import { basename, dirname, extname } from "node:path";
+
+const LOAD_FAILURE_PATTERN = /Failed to load url (\S+)/;
+const INDEX_NAME = "index";
+const NAMELESS_URLS = new Set(["", ".", ".."]);
+
+const fileName = (path: string): string => basename(path, extname(path));
+
+const missingImportName = (cause: unknown): string | null => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const [, url] = LOAD_FAILURE_PATTERN.exec(message) ?? [];
+
+    if (url === undefined) {
+        return null;
+    }
+
+    const name = fileName(url);
+
+    return NAMELESS_URLS.has(name) ? null : name;
+};
+
+const isMissingImport = (createdPath: string, name: string): boolean => {
+    const created = fileName(createdPath);
+
+    if (created === name) {
+        return true;
+    }
+
+    return created === INDEX_NAME && basename(dirname(createdPath)) === name;
+};
+
+export { isMissingImport, missingImportName };

package/src/dev/runner-deps.ts

@@ -1,12 +1,19 @@
 import { loadConfig } from "@gtkx/config";
 import * as Gio from "@gtkx/gi/gio";
 import { quitApplication } from "@gtkx/runtime";
+import { type ApplicationInstance, getApplicationInstance } from "@gtkx/runtime/internal";
 import { info, installGracefulShutdown } from "@gtkx/utils";
+import { readFile } from "node:fs/promises";
 import { createServer } from "vite";
 import type { DevRunnerDeps } from "./runner.js";
 import { startMcpClient, stopMcpClient } from "../mcp/index.js";
-import { setTestingModuleLoader } from "../mcp/testing-loader.js";
-import { isRefreshBoundary, performRefresh } from "../refresh-runtime.js";
+import {
+    mergeTestingModule,
+    setTestingModuleLoader,
+    type TestingInternalModule,
+    type TestingPublicModule,
+} from "../mcp/testing-loader.js";
+import { isRefreshBoundary, performRefresh, staleExportName } from "../refresh-runtime.js";
 import { gtkxFastRefresh } from "../vite-plugins/fast-refresh/swc-refresh.js";
 import { gtkxVitePlugins } from "../vite-plugins/index.js";
 import { gtkxReactDomPrebundle } from "../vite-plugins/react-dom-prebundle.js";
@@ -16,11 +23,17 @@ const APPLICATION_POLL_INTERVAL_MS = 50;
 
 const currentApplicationId = (): string | null => Gio.Application.getDefault()?.applicationId ?? null;
 
-const waitForApplicationId = async (timeoutMs: number): Promise<string | null> => {
+const currentApplicationInstance = (): ApplicationInstance => {
+    const application = Gio.Application.getDefault();
+
+    return application === null ? "unregistered" : getApplicationInstance(application);
+};
+
+const waitForApplicationId = async (timeoutMs: number, shouldKeepWaiting: () => boolean): Promise<string | null> => {
     const deadline = Date.now() + timeoutMs;
     let applicationId = currentApplicationId();
 
-    while (applicationId === null && Date.now() < deadline) {
+    while (applicationId === null && Date.now() < deadline && shouldKeepWaiting()) {
         await new Promise((resolve) => setTimeout(resolve, APPLICATION_POLL_INTERVAL_MS));
         applicationId = currentApplicationId();
     }
@@ -28,6 +41,8 @@ const waitForApplicationId = async (timeoutMs: number): Promise<string | null> =
     return applicationId;
 };
 
+const readFileRevision = (path: string): Promise<string> => readFile(path, "utf8");
+
 const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     createServer,
     waitForApplicationId,
@@ -37,7 +52,14 @@ const defaultDevRunnerDeps = (): DevRunnerDeps => ({
         return loaded.config.applicationId;
     },
     startMcpClient: (applicationId, loadAppModule) => {
-        setTestingModuleLoader(() => loadAppModule("@gtkx/testing") as Promise<typeof import("@gtkx/testing")>);
+        setTestingModuleLoader(async () => {
+            const [publicApi, internals] = await Promise.all([
+                loadAppModule("@gtkx/testing") as Promise<TestingPublicModule>,
+                loadAppModule("@gtkx/testing/internal") as Promise<TestingInternalModule>,
+            ]);
+
+            return mergeTestingModule(publicApi, internals);
+        });
 
         return startMcpClient(applicationId);
     },
@@ -45,7 +67,11 @@ const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     watchApplicationShutdown: (onShutdown) => {
         Gio.Application.getDefault()?.on("shutdown", onShutdown);
     },
-    isApplicationRegistered: () => Gio.Application.getDefault()?.getIsRegistered() === true,
+    watchUncaughtErrors: (onUncaughtError) => {
+        process.on("uncaughtException", onUncaughtError);
+        process.on("unhandledRejection", onUncaughtError);
+    },
+    getApplicationInstance: currentApplicationInstance,
     installShutdownHandlers: (onSignal) => {
         installGracefulShutdown({ onSignal });
     },
@@ -58,6 +84,8 @@ const defaultDevRunnerDeps = (): DevRunnerDeps => ({
     },
     performRefresh,
     isRefreshBoundary,
+    staleExportName,
+    readFileRevision,
     plugins: () => [...gtkxVitePlugins(DEV_MODE), ...gtkxFastRefresh(), gtkxReactDomPrebundle()],
     log: info,
     exit: (code: number): never => process.exit(code),