@mittwald/cli 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/commands/user/ssh-key/list.js

@@ -0,0 +1,26 @@
+import { ListBaseCommand } from "../../../ListBaseCommand.js";
+import { buildCreatedAtColumn } from "../../../lib/viewhelpers/list_column_date.js";
+export default class List extends ListBaseCommand {
+    static description = "Get your stored ssh keys";
+    static args = {};
+    static flags = {
+        ...ListBaseCommand.baseFlags,
+    };
+    async getData() {
+        return await this.apiClient.user.listSshKeys();
+    }
+    mapData(data) {
+        return data.sshKeys ?? [];
+    }
+    getColumns() {
+        return {
+            sshKeyId: {
+                header: "ID",
+                minWidth: 36,
+            },
+            comment: {},
+            fingerprint: {},
+            createdAt: buildCreatedAtColumn(this.flags),
+        };
+    }
+}

package/dist/lib/api_consistency.d.ts

@@ -0,0 +1,2 @@
+import { AxiosInstance } from "@mittwald/api-client-commons";
+export declare function configureConsistencyHandling(axios: AxiosInstance): void;

package/dist/lib/api_consistency.js

@@ -0,0 +1,27 @@
+import debug from "debug";
+const d = debug("mw:api-consistency");
+export function configureConsistencyHandling(axios) {
+    let lastEventId = undefined;
+    let mutatedPaths = undefined;
+    axios.interceptors.request.use((config) => {
+        if (lastEventId !== undefined &&
+            mutatedPaths?.some((path) => config.url?.startsWith(path))) {
+            d("setting if-event-reached to %o", lastEventId);
+            config.headers["if-event-reached"] = lastEventId;
+        }
+        return config;
+    });
+    axios.interceptors.response.use((response) => {
+        const isMutatingRequest = ["post", "put", "delete", "patch"].indexOf(response.config?.method?.toLowerCase() ?? "") >= 0;
+        const headers = response.headers;
+        if (headers.has("etag") && isMutatingRequest) {
+            lastEventId = headers.get("etag");
+            const mutatedPath = response.config?.url;
+            if (mutatedPath !== undefined) {
+                mutatedPaths = [mutatedPath];
+            }
+            d("setting last event id to %o after mutating request for path %o", headers["etag"], mutatedPath);
+        }
+        return response;
+    });
+}

package/dist/lib/api_retry.d.ts

@@ -0,0 +1,2 @@
+import { AxiosInstance } from "@mittwald/api-client-commons";
+export declare function configureAxiosRetry(axios: AxiosInstance): void;

package/dist/lib/api_retry.js

@@ -0,0 +1,43 @@
+import debug from "debug";
+import axiosRetry from "axios-retry";
+const d = debug("mw:api-retry");
+export function configureAxiosRetry(axios) {
+    let shouldRetryAccessDenied = false;
+    axios.interceptors.request.use((config) => {
+        return {
+            ...config,
+            validateStatus: (status) => status < 300,
+        };
+    });
+    axios.interceptors.request.use((config) => {
+        if (config.method?.toLowerCase() === "post") {
+            shouldRetryAccessDenied = true;
+        }
+        return config;
+    });
+    axiosRetry(axios, {
+        retries: 10,
+        retryDelay: axiosRetry.exponentialDelay,
+        onRetry(count, error, config) {
+            if (error.response?.status === 412 && config.headers !== undefined) {
+                delete config.headers["if-event-reached"];
+            }
+            d("retrying request after %d attempts; error: %o", count, error.message);
+        },
+        retryCondition(error) {
+            if (error.code === "ERR_FR_TOO_MANY_REDIRECTS") {
+                return false;
+            }
+            if (axiosRetry.isNetworkOrIdempotentRequestError(error)) {
+                return true;
+            }
+            const isSafeRequest = error.config?.method?.toLowerCase() === "get";
+            const isPreconditionFailed = error.response?.status === 412;
+            const isAccessDenied = error.response?.status === 403;
+            if (isPreconditionFailed) {
+                return true;
+            }
+            return isSafeRequest && isAccessDenied && shouldRetryAccessDenied;
+        },
+    });
+}

package/dist/lib/app/Installer.d.ts

@@ -0,0 +1,22 @@
+import { ArgOutput, OutputFlags } from "@oclif/core/lib/interfaces/parser.js";
+import { AvailableFlagName, RelevantFlagInput } from "./flags.js";
+import React from "react";
+import { MittwaldAPIV2Client } from "@mittwald/api-client";
+import { Config } from "@oclif/core";
+export interface AppInstallationResult {
+    appInstallationId: string;
+}
+export declare class AppInstaller<TFlagName extends AvailableFlagName> {
+    readonly appId: string;
+    readonly appName: string;
+    readonly appSupportedFlags: readonly TFlagName[];
+    readonly description: string;
+    mutateFlags?: (flags: RelevantFlagInput<readonly TFlagName[]>) => unknown;
+    private static makeDescription;
+    constructor(appId: string, appName: string, appSupportedFlags: readonly TFlagName[]);
+    get flags(): RelevantFlagInput<readonly TFlagName[]>;
+    exec(apiClient: MittwaldAPIV2Client, args: ArgOutput, flags: OutputFlags<RelevantFlagInput<(TFlagName | "wait")[]>>, config: Config): Promise<AppInstallationResult>;
+    render(result: AppInstallationResult, flags: {
+        quiet: boolean;
+    }): React.ReactNode;
+}

package/dist/lib/app/Installer.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { makeProcessRenderer } from "../../rendering/process/process_flags.js";
+import { withProjectId } from "../project/flags.js";
+import { autofillFlags, provideSupportedFlags, } from "./flags.js";
+import { normalizeToAppVersionUuid } from "./versions.js";
+import { triggerAppInstallation } from "./install.js";
+import { waitUntilAppIsInstalled } from "./wait.js";
+import { Success } from "../../rendering/react/components/Success.js";
+export class AppInstaller {
+    appId;
+    appName;
+    appSupportedFlags;
+    description;
+    mutateFlags;
+    static makeDescription(appName) {
+        return `Creates new ${appName} installation.`;
+    }
+    constructor(appId, appName, appSupportedFlags) {
+        this.appId = appId;
+        this.appName = appName;
+        this.appSupportedFlags = appSupportedFlags;
+        this.description = AppInstaller.makeDescription(appName);
+    }
+    get flags() {
+        const flags = provideSupportedFlags(this.appSupportedFlags, this.appName);
+        if (this.mutateFlags) {
+            this.mutateFlags(flags);
+        }
+        return flags;
+    }
+    async exec(apiClient, args, flags, config) {
+        const process = makeProcessRenderer(flags, `Installing ${this.appName}`);
+        const projectId = await withProjectId(apiClient, "flag", flags, args, config);
+        await autofillFlags(apiClient, process, this.appSupportedFlags, flags, projectId, this.appName);
+        const appVersion = await normalizeToAppVersionUuid(apiClient, "version" in flags ? flags.version : "latest", process, this.appId);
+        const appInstallationId = await triggerAppInstallation(apiClient, process, projectId, flags, appVersion);
+        let successText;
+        if (flags.wait) {
+            await waitUntilAppIsInstalled(apiClient, process, appInstallationId);
+            successText = `Your ${this.appName} installation is now complete. Have fun! 🎉`;
+        }
+        else {
+            successText = `Your ${this.appName} installation has started. Have fun when it's ready! 🎉`;
+        }
+        process.complete(_jsx(Success, { children: successText }));
+        return { appInstallationId };
+    }
+    render(result, flags) {
+        if (flags.quiet) {
+            return result.appInstallationId;
+        }
+        return undefined;
+    }
+}

package/dist/lib/app/flags.d.ts

@@ -0,0 +1,28 @@
+import { MittwaldAPIV2Client } from "@mittwald/api-client";
+import { ProcessRenderer } from "../../rendering/process/process.js";
+import { ProcessFlags } from "../../rendering/process/process_flags.js";
+import { BooleanFlag, FlagInput, OptionFlag, OutputFlags } from "@oclif/core/lib/interfaces/parser.js";
+export declare const appInstallationFlags: import("../context_flags.js").ContextFlags<"installation", "installation-id">, appInstallationArgs: import("../context_flags.js").ContextArgs<"installation", "installation-id">, withAppInstallationId: (apiClient: MittwaldAPIV2Client, command: "flag" | "arg" | import("../context_flags.js").CommandType<"installation", "installation-id">, flags: import("@oclif/core/lib/interfaces/parser.js").FlagOutput, args: import("@oclif/core/lib/interfaces/parser.js").ArgOutput, cfg: import("@oclif/core").Config) => Promise<string>;
+export type AvailableFlagName = keyof AvailableFlags;
+interface AvailableFlags {
+    version: OptionFlag<string>;
+    host: OptionFlag<string | undefined>;
+    "admin-user": OptionFlag<string | undefined>;
+    "admin-email": OptionFlag<string | undefined>;
+    "admin-pass": OptionFlag<string | undefined>;
+    "admin-firstname": OptionFlag<string | undefined>;
+    "admin-lastname": OptionFlag<string | undefined>;
+    "site-title": OptionFlag<string | undefined>;
+    "shop-email": OptionFlag<string | undefined>;
+    "shop-lang": OptionFlag<string | undefined>;
+    "shop-currency": OptionFlag<string | undefined>;
+    "install-mode": OptionFlag<string>;
+    "document-root": OptionFlag<string>;
+    wait: BooleanFlag<boolean | undefined>;
+    entrypoint: OptionFlag<string | undefined>;
+}
+export type RelevantFlags<TFlags extends readonly AvailableFlagName[]> = ProcessFlags & Pick<AvailableFlags, TFlags[number]>;
+export type RelevantFlagInput<TFlags extends readonly AvailableFlagName[]> = FlagInput<RelevantFlags<TFlags>>;
+export declare function provideSupportedFlags<TFlagNames extends readonly AvailableFlagName[]>(requestedFlagNames: TFlagNames, appName: string): RelevantFlagInput<TFlagNames>;
+export declare function autofillFlags(apiClient: MittwaldAPIV2Client, process: ProcessRenderer, necessaryFlags: readonly AvailableFlagName[], flags: Partial<OutputFlags<RelevantFlagInput<AvailableFlagName[]>>>, projectId: string, appName: string): Promise<void>;
+export {};

package/dist/lib/app/flags.js

@@ -0,0 +1,214 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { getDefaultIngressForProject } from "../project/ingress.js";
+import { Value } from "../../rendering/react/components/Value.js";
+import { getProjectShortIdFromUuid } from "../project/shortId.js";
+import { Text } from "ink";
+import { assertStatus } from "@mittwald/api-client-commons";
+import { projectFlags } from "../project/flags.js";
+import { processFlags, } from "../../rendering/process/process_flags.js";
+import { Flags } from "@oclif/core";
+import { generatePasswordWithSpecialChars } from "../password.js";
+import { normalizeAppInstallationId } from "../../normalize_id.js";
+import { makeFlagSet } from "../context_flags.js";
+export const { flags: appInstallationFlags, args: appInstallationArgs, withId: withAppInstallationId, } = makeFlagSet("installation", "i", {
+    displayName: "app installation",
+    normalize: normalizeAppInstallationId,
+});
+function buildFlagsWithDescription(appName) {
+    return {
+        version: Flags.string({
+            required: true,
+            summary: `version of ${appName} to be installed.`,
+            description: `Specify the version in which your ${appName} will be installed. 
+      If unspecified, the ${appName} will be installed in the latest available version.`,
+            default: "latest",
+        }),
+        host: Flags.string({
+            required: false,
+            summary: `host to initially configure your ${appName} installation with; needs to be created separately.`,
+            description: `Specify a host which will be used during the installation and as an initial host for the ${appName} configuration.
+      If unspecified, the default host for the given project will be used. 
+      This does not change the target of the used host and can be changed later by configuring the host and your ${appName} installation.`,
+            default: undefined,
+        }),
+        "admin-user": Flags.string({
+            required: false,
+            summary: "Username for your administrator user.",
+            description: `Username of the first administrator user which will be created during the ${appName} installation. 
+      If unspecified, an adequate username will be generated.
+      After the installation is finished, the username can be changed and additional administrator users can be created.`,
+            default: undefined,
+        }),
+        "admin-email": Flags.string({
+            required: false,
+            summary: "email address of your administrator user.",
+            description: `email address that will be used for the first administrator user that is created during the ${appName} installation.
+      If unspecified, email address of your mStudio account will be used. This email address can be changed after the installation is finished.`,
+            default: undefined,
+        }),
+        "admin-pass": Flags.string({
+            required: false,
+            summary: "password of your administrator user.",
+            description: `The password that will be used for the first administrator user that is created during the ${appName} installation.
+      If unspecified, a random secure password will be generated and printed to stdout. This password can be changed after the installation is finished`,
+            default: undefined,
+        }),
+        "admin-firstname": Flags.string({
+            required: false,
+            summary: "first name of your administrator user.",
+            description: `The first name that will be used for the first administrator user that is created during the ${appName} installation.
+      If unspecified, the first name of your mStudio user will be used. This value can be changed after the installation is finished.`,
+            default: undefined,
+        }),
+        "admin-lastname": Flags.string({
+            required: false,
+            summary: "Lastname of your administrator user.",
+            description: `The last name that will be used for the first administrator user that is created during the ${appName} installation.
+      If unspecified, the last name of your mStudio user will be used. This value can be changed after the installation is finished.`,
+            default: undefined,
+        }),
+        "site-title": Flags.string({
+            required: false,
+            summary: `site title for your ${appName} installation.`,
+            description: `The site title for this ${appName} installation. It is also the title shown in the app overview in the mStudio and the CLI.
+      If unspecified, the application name and the given project ID will be used. The title can be changed after the installation is finished`,
+            default: undefined,
+        }),
+        "shop-email": Flags.string({
+            required: false,
+            summary: `email address your ${appName} will be working with.`,
+            description: `The email address your ${appName} installation will be using for correspondence with end users.
+      If unspecified, your mStudio account email will be used. This email address can be changed after the installation is finished.`,
+            default: undefined,
+        }),
+        "shop-lang": Flags.string({
+            required: false,
+            summary: `language your ${appName} will be working with.`,
+            description: `The default language your ${appName} installation will be using. The front- and back end will be displayed using the given language.
+      If unspecified, this will default to German (de_DE). The language can be changed after the installation is finished.`,
+            default: undefined,
+        }),
+        "shop-currency": Flags.string({
+            required: false,
+            summary: `Currency your ${appName} will be working with.`,
+            description: `The default currency your ${appName} shop communicates prices and calculates transactions with.
+      If unspecified, this will default to EUR(€). The currency can be changed after the installation is finished.`,
+            default: undefined,
+        }),
+        "install-mode": Flags.string({
+            required: true,
+            summary: `The installation mode your ${appName} will be installed with.`,
+            description: `${appName} can be installed in one of two different ways: either as a composer project or in a more manual fashion using the source directory and the ${appName} console install wizard.
+      If unspecified, this will default to a composer-based installation. This can not be changed later.`,
+            options: ["composer", "symlink"],
+            default: "composer",
+        }),
+        "document-root": Flags.string({
+            required: true,
+            summary: `the document root from which your ${appName} will be served (relative to the installation path)`,
+            description: "This is the document root from which the files of your application will be served by the web server. This directory is specified relative to the installation path.",
+            default: "/",
+        }),
+        entrypoint: Flags.string({
+            summary: `the command that should be used to start your ${appName} application.`,
+            description: "This is the command that should be used to start your application; the app is required to run in the foreground, and to listen on the port specified by the PORT environment variable.",
+            required: false,
+            default: undefined,
+        }),
+        wait: Flags.boolean({
+            char: "w",
+            description: `wait for your ${appName} to be ready.`,
+        }),
+    };
+}
+export function provideSupportedFlags(requestedFlagNames, appName) {
+    const availableFlags = buildFlagsWithDescription(appName);
+    const supportedFlags = requestedFlagNames.reduce((collector, currentValue) => {
+        return {
+            ...collector,
+            [currentValue]: availableFlags[currentValue],
+        };
+    }, {});
+    const flagsToReturn = {
+        ...projectFlags,
+        ...processFlags,
+        ...supportedFlags,
+    };
+    return flagsToReturn;
+}
+export async function autofillFlags(apiClient, process, necessaryFlags, flags, projectId, appName) {
+    const ownUser = await apiClient.user.getOwnAccount();
+    assertStatus(ownUser, 200);
+    // Version
+    if (necessaryFlags.includes("version") && !flags.version) {
+        flags.version = "latest";
+    }
+    // Host
+    if (necessaryFlags.includes("host") && !flags.host) {
+        flags.host =
+            "https://" + (await getDefaultIngressForProject(apiClient, projectId));
+        process.addInfo(_jsxs(Text, { children: ["Using default Host ", _jsx(Value, { children: flags["host"] })] }));
+    }
+    // Title
+    if (necessaryFlags.includes("site-title") && !flags["site-title"]) {
+        flags["site-title"] =
+            appName + " " + (await getProjectShortIdFromUuid(apiClient, projectId));
+    }
+    // Admin User
+    if (necessaryFlags.includes("admin-user") && !flags["admin-user"]) {
+        if (ownUser.data.person) {
+            flags["admin-user"] =
+                ownUser.data.person.firstName.charAt(0).toLowerCase() +
+                    ownUser.data.person.lastName.toLowerCase();
+        }
+        else {
+            flags["admin-user"] = await getProjectShortIdFromUuid(apiClient, projectId);
+        }
+        process.addInfo(_jsxs(Text, { children: ["Using generated Admin User: ", _jsx(Value, { children: flags["admin-user"] })] }));
+    }
+    // Admin Pass
+    if (necessaryFlags.includes("admin-pass") && !flags["admin-pass"]) {
+        flags["admin-pass"] = generatePasswordWithSpecialChars();
+        process.addInfo(_jsxs(Text, { children: ["Using generated random Admin Pass: ", _jsx(Value, { children: flags["admin-pass"] })] }));
+    }
+    // Admin Firstname
+    if (necessaryFlags.includes("admin-firstname") && !flags["admin-firstname"]) {
+        if (ownUser.data.person) {
+            flags["admin-firstname"] = ownUser.data.person.firstName;
+        }
+        else {
+            flags["admin-firstname"] = "Max";
+        }
+        process.addInfo(_jsxs(Text, { children: ["Using mStudio firstname as Admin firstname (", _jsx(Value, { children: flags["admin-firstname"] }), ")"] }));
+    }
+    // Admin Lastname
+    if (necessaryFlags.includes("admin-lastname") && !flags["admin-lastname"]) {
+        if (ownUser.data.person) {
+            flags["admin-lastname"] = ownUser.data.person.lastName;
+        }
+        else {
+            flags["admin-lastname"] = "Mustermann";
+        }
+        process.addInfo(_jsxs(Text, { children: ["Using mStudio lastname as Admin lastname (", _jsx(Value, { children: flags["admin-lastname"] }), ")"] }));
+    }
+    // Admin E-Mail
+    if (necessaryFlags.includes("admin-email") && !flags["admin-email"]) {
+        flags["admin-email"] = ownUser.data.email;
+        process.addInfo(_jsxs(Text, { children: ["Using mStudio email as Admin email (", _jsx(Value, { children: flags["admin-email"] }), ")"] }));
+    }
+    // Shop E-Mail
+    if (necessaryFlags.includes("shop-email") && !flags["shop-email"]) {
+        flags["shop-email"] = ownUser.data.email;
+        process.addInfo(_jsxs(Text, { children: ["Using mStudio email as Shop email (", _jsx(Value, { children: flags["shop-email"] }), ")"] }));
+    }
+    // Shop Language Code
+    if (necessaryFlags.includes("shop-lang") && !flags["shop-lang"]) {
+        flags["shop-lang"] = "de-DE";
+        process.addInfo(_jsx(Text, { children: "Using default shop language 'de_DE'." }));
+    }
+    // Shop Currency
+    if (necessaryFlags.includes("shop-currency") && !flags["shop-currency"]) {
+        flags["shop-currency"] = "EUR";
+        process.addInfo(_jsx(Text, { children: "Using default shop currency '\u20AC'." }));
+    }
+}

package/dist/lib/app/hooks.d.ts

@@ -0,0 +1,12 @@
+import type { MittwaldAPIV2 } from "@mittwald/api-client";
+type AppSystemSoftware = MittwaldAPIV2.Components.Schemas.AppSystemSoftware;
+type AppSystemSoftwareVersion = MittwaldAPIV2.Components.Schemas.AppSystemSoftwareVersion;
+type AppAppVersion = MittwaldAPIV2.Components.Schemas.AppAppVersion;
+type AppApp = MittwaldAPIV2.Components.Schemas.AppApp;
+type AppAppInstallation = MittwaldAPIV2.Components.Schemas.AppAppInstallation;
+export declare function useApp(appId: string): AppApp;
+export declare function useAppInstallation(appInstallationId: string): AppAppInstallation;
+export declare function useAppVersion(appId: string, appVersionId: string): AppAppVersion;
+export declare function useSystemSoftware(systemSoftwareId: string): AppSystemSoftware;
+export declare function useSystemSoftwareVersion(systemSoftwareId: string, systemSoftwareVersionId: string): AppSystemSoftwareVersion;
+export {};

package/dist/lib/app/hooks.js

@@ -0,0 +1,43 @@
+import { usePromise } from "@mittwald/react-use-promise";
+import { assertStatus } from "@mittwald/api-client-commons";
+import { useRenderContext } from "../../rendering/react/context.js";
+export function useApp(appId) {
+    const { apiClient } = useRenderContext();
+    const app = usePromise((id) => apiClient.app.getApp({ appId: id }), [appId]);
+    assertStatus(app, 200);
+    return app.data;
+}
+export function useAppInstallation(appInstallationId) {
+    const { apiClient } = useRenderContext();
+    const appInstallation = usePromise((id) => apiClient.app.getAppinstallation({
+        appInstallationId: id,
+    }), [appInstallationId]);
+    assertStatus(appInstallation, 200);
+    return appInstallation.data;
+}
+export function useAppVersion(appId, appVersionId) {
+    const { apiClient } = useRenderContext();
+    const appVersion = usePromise((appId, appVersionId) => apiClient.app.getAppversion({
+        appId,
+        appVersionId,
+    }), [appId, appVersionId]);
+    assertStatus(appVersion, 200);
+    return appVersion.data;
+}
+export function useSystemSoftware(systemSoftwareId) {
+    const { apiClient } = useRenderContext();
+    const systemSoftware = usePromise((id) => apiClient.app.getSystemsoftware({
+        systemSoftwareId: id,
+    }), [systemSoftwareId]);
+    assertStatus(systemSoftware, 200);
+    return systemSoftware.data;
+}
+export function useSystemSoftwareVersion(systemSoftwareId, systemSoftwareVersionId) {
+    const { apiClient } = useRenderContext();
+    const systemSoftwareVersion = usePromise((systemSoftwareId, systemSoftwareVersionId) => apiClient.app.getSystemsoftwareversion({
+        systemSoftwareId,
+        systemSoftwareVersionId,
+    }), [systemSoftwareId, systemSoftwareVersionId]);
+    assertStatus(systemSoftwareVersion, 200);
+    return systemSoftwareVersion.data;
+}

package/dist/lib/app/install.d.ts

@@ -0,0 +1,5 @@
+import { MittwaldAPIV2, MittwaldAPIV2Client } from "@mittwald/api-client";
+import { ProcessRenderer } from "../../rendering/process/process.js";
+type AppAppVersion = MittwaldAPIV2.Components.Schemas.AppAppVersion;
+export declare function triggerAppInstallation(apiClient: MittwaldAPIV2Client, process: ProcessRenderer, projectId: string, flags: Record<string, string>, appVersion: AppAppVersion): Promise<string>;
+export {};

package/dist/lib/app/install.js

@@ -0,0 +1,42 @@
+import { assertStatus } from "@mittwald/api-client-commons";
+export async function triggerAppInstallation(apiClient, process, projectId, flags, appVersion) {
+    const appInstallationId = await process.runStep("starting installation", async () => {
+        const result = await apiClient.app.requestAppinstallation({
+            projectId,
+            data: {
+                appVersionId: appVersion.id,
+                description: flags["site-title"],
+                updatePolicy: "none",
+                userInputs: Object.keys(flags).map((k) => ({
+                    name: k.replace("-", "_"),
+                    value: flags[k],
+                })),
+            },
+        });
+        assertStatus(result, 201);
+        return result.data.id;
+    });
+    await process.runStep("waiting for installation to be retrievable", async () => {
+        for (let attempts = 0; attempts < 10; attempts++) {
+            const result = await apiClient.app.getAppinstallation({
+                appInstallationId,
+            });
+            if (result.status === 200) {
+                return result.data;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    });
+    if ("document-root" in flags && flags["document-root"] !== "/") {
+        await process.runStep("setting document root", async () => {
+            const result = await apiClient.app.patchAppinstallation({
+                appInstallationId,
+                data: {
+                    customDocumentRoot: flags["document-root"],
+                },
+            });
+            assertStatus(result, 204);
+        });
+    }
+    return appInstallationId;
+}

package/dist/lib/app/uuid.d.ts

@@ -0,0 +1,41 @@
+import { MittwaldAPIV2, MittwaldAPIV2Client } from "@mittwald/api-client";
+type AppAppVersion = MittwaldAPIV2.Components.Schemas.AppAppVersion;
+type AppApp = MittwaldAPIV2.Components.Schemas.AppApp;
+/**
+ * Lookup an app by its UUID
+ *
+ * @param apiClient
+ * @param appId
+ */
+export declare function getAppFromUuid(apiClient: MittwaldAPIV2Client, appId: string): Promise<AppApp>;
+/**
+ * Lookup an app version by its UUID
+ *
+ * @param apiClient
+ * @param appId
+ * @param appVersionId
+ */
+export declare function getAppVersionFromUuid(apiClient: MittwaldAPIV2Client, appId: string, appVersionId: string): Promise<AppAppVersion>;
+/**
+ * Lookup an app by its human readable name
+ *
+ * @param apiClient
+ * @param appName
+ */
+export declare function getAppUuidFromAppName(apiClient: MittwaldAPIV2Client, appName: string): Promise<string>;
+/**
+ * Lookup an app name by its UUID
+ *
+ * @param apiClient
+ * @param uuid
+ */
+export declare function getAppNameFromUuid(apiClient: MittwaldAPIV2Client, uuid: string): Promise<string>;
+/**
+ * Lookup an app version number by its UUID
+ *
+ * @param apiClient
+ * @param appId
+ * @param appVersionId
+ */
+export declare function getAppVersionNumberFromUuid(apiClient: MittwaldAPIV2Client, appId: string, appVersionId: string): Promise<string>;
+export {};

package/dist/lib/app/uuid.js

@@ -0,0 +1,77 @@
+import { isUuid } from "../../normalize_id.js";
+import { assertStatus, } from "@mittwald/api-client";
+/**
+ * Lookup an app by its UUID
+ *
+ * @param apiClient
+ * @param appId
+ */
+export async function getAppFromUuid(apiClient, appId) {
+    const result = await apiClient.app.getApp({ appId });
+    assertStatus(result, 200);
+    return result.data;
+}
+/**
+ * Lookup an app version by its UUID
+ *
+ * @param apiClient
+ * @param appId
+ * @param appVersionId
+ */
+export async function getAppVersionFromUuid(apiClient, appId, appVersionId) {
+    if (!isUuid(appId) && !isUuid(appVersionId)) {
+        throw new Error("Given UUID not valid.");
+    }
+    const appVersion = await apiClient.app.getAppversion({
+        appId: appId,
+        appVersionId: appVersionId,
+    });
+    assertStatus(appVersion, 200);
+    return appVersion.data;
+}
+/**
+ * Convert an app name in a format suitable for fuzzy comparison (ignore casing,
+ * punctuation, etc.)
+ *
+ * @param appName
+ */
+function canonicalizeAppName(appName) {
+    return appName.toLowerCase().replace(/[!. ]/g, "");
+}
+/**
+ * Lookup an app by its human readable name
+ *
+ * @param apiClient
+ * @param appName
+ */
+export async function getAppUuidFromAppName(apiClient, appName) {
+    const apps = await apiClient.app.listApps();
+    assertStatus(apps, 200);
+    const appNameCanonical = canonicalizeAppName(appName);
+    const appNameMatches = (item) => canonicalizeAppName(item.name) === appNameCanonical;
+    const foundApp = apps.data.find(appNameMatches);
+    if (foundApp) {
+        return foundApp.id;
+    }
+    throw new Error("Access Denied.");
+}
+/**
+ * Lookup an app name by its UUID
+ *
+ * @param apiClient
+ * @param uuid
+ */
+export async function getAppNameFromUuid(apiClient, uuid) {
+    return (await getAppFromUuid(apiClient, uuid)).name;
+}
+/**
+ * Lookup an app version number by its UUID
+ *
+ * @param apiClient
+ * @param appId
+ * @param appVersionId
+ */
+export async function getAppVersionNumberFromUuid(apiClient, appId, appVersionId) {
+    return (await getAppVersionFromUuid(apiClient, appId, appVersionId))
+        .externalVersion;
+}

package/dist/lib/app/versions.d.ts

@@ -0,0 +1,7 @@
+import { MittwaldAPIV2, MittwaldAPIV2Client } from "@mittwald/api-client";
+import { ProcessRenderer } from "../../rendering/process/process.js";
+type AppVersion = MittwaldAPIV2.Components.Schemas.AppAppVersion;
+export declare function normalizeToAppVersionUuid(apiClient: MittwaldAPIV2Client, version: string, process: ProcessRenderer, appUuid: string): Promise<MittwaldAPIV2.Components.Schemas.AppAppVersion>;
+export declare function getLatestAvailableAppVersionForApp(apiClient: MittwaldAPIV2Client, appId: string): Promise<AppVersion | undefined>;
+export declare function getAppVersionUuidFromAppVersion(apiClient: MittwaldAPIV2Client, appId: string, appVersion: string | undefined): Promise<AppVersion | undefined>;
+export {};