@mittwald/cli 1.6.0 → 1.8.0

package/README.md

@@ -107,7 +107,7 @@ USAGE
 * [`mw app`](docs/app.md) - Manage apps, and app installations in your projects
 * [`mw autocomplete`](docs/autocomplete.md) - Display autocomplete installation instructions.
 * [`mw backup`](docs/backup.md) - Manage backups of your projects
-* [`mw container`](docs/container.md) - Delete a container
+* [`mw container`](docs/container.md) - Manage containers
 * [`mw context`](docs/context.md) - Save certain environment parameters for later use
 * [`mw conversation`](docs/conversation.md) - Manage your support cases
 * [`mw cronjob`](docs/cronjob.md) - Manage cronjobs of your projects

package/dist/commands/app/upgrade.d.ts

@@ -14,5 +14,19 @@ export declare class UpgradeApp extends ExecRenderBaseCommand<typeof UpgradeApp,
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     protected exec(): Promise<void>;
+    /**
+     * Determines the target application version based on the provided input and
+     * available upgrade candidates.
+     *
+     * @param currentApp The current application instance.
+     * @param currentAppVersion The current version of the application.
+     * @param targetAppVersionCandidates List of potential target application
+     *   versions.
+     * @param process The process renderer to handle user interactions and display
+     *   information.
+     * @returns The determined target application version, or undefined if not
+     *   resolved.
+     */
+    private determineTargetAppVersion;
     protected render(): ReactNode;
 }

package/dist/commands/app/upgrade.js

@@ -11,7 +11,7 @@ import { Success } from "../../rendering/react/components/Success.js";
 import { waitUntilAppStateHasNormalized } from "../../lib/resources/app/wait.js";
 import { assertStatus } from "@mittwald/api-client-commons";
 import { waitFlags } from "../../lib/wait.js";
-import semver from "semver/preload.js";
+import semver from "semver";
 export class UpgradeApp extends ExecRenderBaseCommand {
     static description = "Upgrade app installation to target version";
     static args = {
@@ -19,11 +19,11 @@ export class UpgradeApp extends ExecRenderBaseCommand {
     };
     static flags = {
         "target-version": Flags.string({
-            description: "target version to upgrade app to; if omitted, target version will be prompted interactively",
+            description: "target version to upgrade app to; if omitted, target version will be prompted interactively. May also be a semantic versioning range, e.g. ^1.0.0. If set to 'latest', the latest available version will be used.",
         }),
         force: Flags.boolean({
             char: "f",
-            description: "Do not ask for confirmation.",
+            summary: "do not ask for confirmation.",
         }),
         ...projectFlags,
         ...processFlags,
@@ -43,25 +43,7 @@ export class UpgradeApp extends ExecRenderBaseCommand {
             process.complete(_jsxs(Text, { children: ["Your ", currentApp.name, " ", currentAppVersion.externalVersion, " is already Up-To-Date. \u2705"] }));
             return;
         }
-        let targetAppVersion;
-        if (this.flags["target-version"] == "latest") {
-            targetAppVersion =
-                (await getLatestAvailableTargetAppVersionForAppVersionUpgradeCandidates(this.apiClient, currentApp.id, currentAppVersion.id));
-        }
-        else if (this.flags["target-version"]) {
-            const targetVersionMatchFromCandidates = targetAppVersionCandidates.find((targetAppVersionCandidate) => targetAppVersionCandidate.externalVersion ===
-                this.flags["target-version"]);
-            if (targetVersionMatchFromCandidates) {
-                targetAppVersion = targetVersionMatchFromCandidates;
-            }
-            else {
-                process.addInfo(_jsx(Text, { children: "The given target upgrade version does not seem to be a valid upgrade candidate." }));
-                targetAppVersion = (await forceTargetVersionSelection(process, this.apiClient, targetAppVersionCandidates, currentApp, currentAppVersion));
-            }
-        }
-        else {
-            targetAppVersion = (await forceTargetVersionSelection(process, this.apiClient, targetAppVersionCandidates, currentApp, currentAppVersion));
-        }
+        const targetAppVersion = await this.determineTargetAppVersion(currentApp, currentAppVersion, targetAppVersionCandidates, process);
         if (!targetAppVersion) {
             process.error("Target app version could not be determined properly.");
             ux.exit(1);
@@ -121,6 +103,37 @@ export class UpgradeApp extends ExecRenderBaseCommand {
         }
         await process.complete(_jsx(Success, { children: successText }));
     }
+    /**
+     * Determines the target application version based on the provided input and
+     * available upgrade candidates.
+     *
+     * @param currentApp The current application instance.
+     * @param currentAppVersion The current version of the application.
+     * @param targetAppVersionCandidates List of potential target application
+     *   versions.
+     * @param process The process renderer to handle user interactions and display
+     *   information.
+     * @returns The determined target application version, or undefined if not
+     *   resolved.
+     */
+    async determineTargetAppVersion(currentApp, currentAppVersion, targetAppVersionCandidates, process) {
+        const targetAppVersionString = this.flags["target-version"];
+        if (targetAppVersionString == "latest") {
+            return await getLatestAvailableTargetAppVersionForAppVersionUpgradeCandidates(this.apiClient, currentApp.id, currentAppVersion.id);
+        }
+        if (targetAppVersionString) {
+            const exactVersionMatch = targetAppVersionCandidates.find((v) => v.externalVersion === targetAppVersionString);
+            if (exactVersionMatch) {
+                return exactVersionMatch;
+            }
+            const semverMatch = targetAppVersionCandidates.findLast((v) => semver.satisfies(v.externalVersion, targetAppVersionString));
+            if (semverMatch) {
+                return semverMatch;
+            }
+            process.addInfo(_jsx(Text, { children: "The given target upgrade version does not seem to be a valid upgrade candidate." }));
+        }
+        return await forceTargetVersionSelection(process, this.apiClient, targetAppVersionCandidates, currentApp, currentAppVersion);
+    }
     render() {
         return true;
     }

package/dist/commands/container/cp.d.ts

@@ -0,0 +1,23 @@
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import { ReactNode } from "react";
+export default class Cp extends ExecRenderBaseCommand<typeof Cp, void> {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        source: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        dest: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        archive: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        recursive: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+        "ssh-user": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "ssh-identity-file": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private parseContainerPath;
+    private buildScpCommand;
+    protected exec(): Promise<void>;
+    protected render(): ReactNode;
+}

package/dist/commands/container/cp.js

@@ -0,0 +1,130 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as fs from "fs";
+import { Args, Flags } from "@oclif/core";
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import { getSSHConnectionForContainer } from "../../lib/resources/ssh/container.js";
+import { sshConnectionFlags } from "../../lib/resources/ssh/flags.js";
+import { withContainerAndStackId } from "../../lib/resources/container/flags.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+import { makeProcessRenderer, processFlags, } from "../../rendering/process/process_flags.js";
+import { spawnInProcess } from "../../rendering/process/process_exec.js";
+import { Success } from "../../rendering/react/components/Success.js";
+export default class Cp extends ExecRenderBaseCommand {
+    static summary = "Copy files/folders between a container and the local filesystem";
+    static description = `The syntax is similar to docker cp:
+- Copy from container to host: mw container cp CONTAINER:SRC_PATH DEST_PATH
+- Copy from host to container: mw container cp SRC_PATH CONTAINER:DEST_PATH
+
+Where CONTAINER can be a container ID, short ID, or service name.`;
+    static examples = [
+        "# Copy a file from container to current directory\n<%= config.bin %> <%= command.id %> mycontainer:/app/config.json .",
+        "# Copy a file from host to container\n<%= config.bin %> <%= command.id %> ./local-file.txt mycontainer:/app/",
+        "# Copy a directory recursively\n<%= config.bin %> <%= command.id %> mycontainer:/var/log ./logs",
+        "# Copy with archive mode (preserve permissions)\n<%= config.bin %> <%= command.id %> -a mycontainer:/app/data ./backup",
+    ];
+    static args = {
+        source: Args.string({
+            description: "Source path (either local path or CONTAINER:PATH)",
+            required: true,
+        }),
+        dest: Args.string({
+            description: "Destination path (either local path or CONTAINER:PATH)",
+            required: true,
+        }),
+    };
+    static flags = {
+        ...processFlags,
+        ...sshConnectionFlags,
+        ...projectFlags,
+        archive: Flags.boolean({
+            char: "a",
+            summary: "archive mode (copy all uid/gid information)",
+            description: "Preserve file permissions and ownership when copying",
+        }),
+        recursive: Flags.boolean({
+            char: "r",
+            summary: "copy directories recursively",
+        }),
+    };
+    parseContainerPath(path) {
+        const colonIndex = path.indexOf(":");
+        if (colonIndex === -1) {
+            return { path };
+        }
+        const container = path.substring(0, colonIndex);
+        const containerPath = path.substring(colonIndex + 1);
+        // Ensure container path starts with / (absolute path)
+        const normalizedPath = containerPath.startsWith("/")
+            ? containerPath
+            : `/${containerPath}`;
+        return { container, path: normalizedPath };
+    }
+    buildScpCommand(source, dest, flags) {
+        const scpArgs = ["-o", "PasswordAuthentication=no"];
+        if (flags.archive) {
+            scpArgs.push("-p");
+        }
+        if (flags.recursive) {
+            scpArgs.push("-r");
+        }
+        scpArgs.push(source, dest);
+        return scpArgs;
+    }
+    async exec() {
+        const { args, flags } = await this.parse(Cp);
+        const sourceParsed = this.parseContainerPath(args.source);
+        const destParsed = this.parseContainerPath(args.dest);
+        // Validate that exactly one of source or dest is a container path
+        if (sourceParsed.container && destParsed.container) {
+            this.error("Cannot copy from container to container. One path must be local.");
+        }
+        if (!sourceParsed.container && !destParsed.container) {
+            this.error("At least one path must specify a container (CONTAINER:PATH format).");
+        }
+        const containerName = sourceParsed.container || destParsed.container;
+        const isDownload = !!sourceParsed.container;
+        const p = makeProcessRenderer(flags, `Copying files ${isDownload ? "from" : "to"} container`);
+        // Get container connection info
+        const [containerId, stackId] = await p.runStep("getting container connection info", async () => {
+            return withContainerAndStackId(this.apiClient, Cp, flags, { "container-id": containerName }, this.config);
+        });
+        const { host, user } = await p.runStep("establishing SSH connection", async () => {
+            return getSSHConnectionForContainer(this.apiClient, containerId, stackId, flags["ssh-user"]);
+        });
+        // Construct source and destination for SCP
+        let scpSource;
+        let scpDest;
+        if (isDownload) {
+            scpSource = `${user}@${host}:${sourceParsed.path}`;
+            scpDest = destParsed.path;
+        }
+        else {
+            scpSource = sourceParsed.path;
+            scpDest = `${user}@${host}:${destParsed.path}`;
+        }
+        // Automatically enable recursive for directories
+        const effectiveFlags = { ...flags };
+        if (!flags.recursive && !isDownload) {
+            try {
+                if (fs.existsSync(scpSource)) {
+                    const stats = fs.statSync(scpSource);
+                    if (stats.isDirectory()) {
+                        effectiveFlags.recursive = true;
+                    }
+                }
+            }
+            catch (ignored) {
+                // Ignore errors when checking if source is a directory
+            }
+        }
+        const scpCommand = this.buildScpCommand(scpSource, scpDest, effectiveFlags);
+        await spawnInProcess(p, `copying files ${isDownload ? "from" : "to"} container`, "/usr/bin/scp", scpCommand);
+        await p.complete(_jsx(CopySuccess, { isDownload: isDownload }));
+    }
+    render() {
+        return undefined;
+    }
+}
+function CopySuccess({ isDownload }) {
+    return (_jsxs(Success, { children: ["Files successfully ", isDownload ? "downloaded from" : "uploaded to", " ", "container! \uD83D\uDE80"] }));
+}

package/dist/commands/container/exec.d.ts

@@ -0,0 +1,25 @@
+import { ExtendedBaseCommand } from "../../lib/basecommands/ExtendedBaseCommand.js";
+export default class Exec extends ExtendedBaseCommand<typeof Exec> {
+    static summary: string;
+    static description: string;
+    static args: {
+        "container-id": import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        command: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        workdir: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        shell: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+        "ssh-user": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "ssh-identity-file": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    /**
+     * Prepare environment variables for the SSH command
+     *
+     * @param envVars Array of environment variables in KEY=VALUE format
+     * @returns Formatted string with export commands
+     */
+    private prepareEnvironmentVariables;
+    run(): Promise<void>;
+}

package/dist/commands/container/exec.js

@@ -0,0 +1,93 @@
+import * as child_process from "child_process";
+import { Args, Flags } from "@oclif/core";
+import { ExtendedBaseCommand } from "../../lib/basecommands/ExtendedBaseCommand.js";
+import { getSSHConnectionForContainer } from "../../lib/resources/ssh/container.js";
+import { sshConnectionFlags } from "../../lib/resources/ssh/flags.js";
+import { sshUsageDocumentation } from "../../lib/resources/ssh/doc.js";
+import { buildSSHClientFlags } from "../../lib/resources/ssh/connection.js";
+import { withContainerAndStackId } from "../../lib/resources/container/flags.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+import shellEscape from "shell-escape";
+export default class Exec extends ExtendedBaseCommand {
+    static summary = "Execute a command in a container via SSH non-interactively.";
+    static description = sshUsageDocumentation;
+    static args = {
+        "container-id": Args.string({
+            description: "ID or short ID of the container to connect to",
+            required: true,
+        }),
+        command: Args.string({
+            description: "Command to execute in the container",
+            required: true,
+        }),
+    };
+    static flags = {
+        ...sshConnectionFlags,
+        ...projectFlags,
+        workdir: Flags.string({
+            char: "w",
+            summary: "working directory where the command will be executed",
+            default: undefined,
+        }),
+        env: Flags.string({
+            char: "e",
+            summary: "environment variables to set for the command (format: KEY=VALUE)",
+            multiple: true,
+        }),
+        shell: Flags.string({
+            summary: "shell to use for the SSH connection",
+            default: "/bin/sh",
+        }),
+    };
+    /**
+     * Prepare environment variables for the SSH command
+     *
+     * @param envVars Array of environment variables in KEY=VALUE format
+     * @returns Formatted string with export commands
+     */
+    prepareEnvironmentVariables(envVars) {
+        return (envVars
+            .map((env) => {
+            const eqIdx = env.indexOf("=");
+            if (eqIdx === -1) {
+                // If no '=', treat the whole string as key with empty value
+                return `export ${shellEscape([env])}=`;
+            }
+            const key = env.slice(0, eqIdx);
+            const value = env.slice(eqIdx + 1);
+            return `export ${shellEscape([key])}=${shellEscape([value])}`;
+        })
+            .join("; ") + "; ");
+    }
+    async run() {
+        const { args, flags } = await this.parse(Exec);
+        const [containerId, stackId] = await withContainerAndStackId(this.apiClient, Exec, flags, this.args, this.config);
+        const { host, user } = await getSSHConnectionForContainer(this.apiClient, containerId, stackId, flags["ssh-user"]);
+        this.log("executing command on %s as %s", host, user);
+        const command = args.command;
+        const workdir = flags.workdir;
+        // Build the command to execute
+        let execCommand = "";
+        // Add environment variables if provided
+        if (flags.env && flags.env.length > 0) {
+            execCommand += this.prepareEnvironmentVariables(flags.env);
+        }
+        // Change to working directory if specified
+        if (workdir !== undefined) {
+            execCommand += `cd ${shellEscape([workdir])} && `;
+        }
+        // Add the actual command
+        execCommand += command;
+        const sshArgs = buildSSHClientFlags(user, host, flags, {
+            interactive: false,
+        });
+        const wrappedExecCommand = shellEscape([flags.shell, "-c", execCommand]);
+        this.debug("running ssh %o, with command %o", sshArgs, wrappedExecCommand);
+        const result = child_process.spawnSync("/usr/bin/ssh", [...sshArgs, wrappedExecCommand], {
+            stdio: "inherit",
+        });
+        if (result.status !== 0) {
+            this.error(`Command failed with exit code ${result.status}`);
+        }
+    }
+}

package/dist/commands/container/port-forward.d.ts

@@ -0,0 +1,20 @@
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import { ReactNode } from "react";
+import PortMapping from "../../lib/units/PortMapping.js";
+export declare class PortForward extends ExecRenderBaseCommand<typeof PortForward, Record<string, never>> {
+    static summary: string;
+    static description: string;
+    static flags: {
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+        "ssh-user": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "ssh-identity-file": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static args: {
+        "container-id": import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        port: import("@oclif/core/interfaces").Arg<PortMapping | undefined, Record<string, unknown>>;
+    };
+    protected exec(): Promise<Record<string, never>>;
+    private getPortMappings;
+    protected render(): ReactNode;
+}

package/dist/commands/container/port-forward.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import { makeProcessRenderer, processFlags, } from "../../rendering/process/process_flags.js";
+import * as cp from "child_process";
+import { Box, Text } from "ink";
+import { Value } from "../../rendering/react/components/Value.js";
+import { Args } from "@oclif/core";
+import { sshConnectionFlags } from "../../lib/resources/ssh/flags.js";
+import { sshUsageDocumentation } from "../../lib/resources/ssh/doc.js";
+import { buildSSHClientFlags } from "../../lib/resources/ssh/connection.js";
+import { withContainerAndStackId } from "../../lib/resources/container/flags.js";
+import { getSSHConnectionForContainer } from "../../lib/resources/ssh/container.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+import PortMapping from "../../lib/units/PortMapping.js";
+import { assertStatus } from "@mittwald/api-client";
+export class PortForward extends ExecRenderBaseCommand {
+    static summary = "Forward a container port to a local port";
+    static description = "This command forwards a TCP port from a container to a local port on your machine. This allows you to connect to services running in the container as if they were running on your local machine.\n\n" +
+        sshUsageDocumentation;
+    static flags = {
+        ...processFlags,
+        ...sshConnectionFlags,
+        ...projectFlags,
+    };
+    static args = {
+        "container-id": Args.string({
+            description: "ID or short ID of the container to connect to",
+            required: true,
+        }),
+        port: PortMapping.arg({
+            summary: "Port mapping in the format 'local-port:container-port'",
+            description: "Specifies the port mapping between your local machine and the container. Format: 'local-port:container-port'. If not specified, available ports will be detected automatically.",
+            required: false,
+        }),
+    };
+    async exec() {
+        const [serviceId, stackId] = await withContainerAndStackId(this.apiClient, PortForward, this.flags, this.args, this.config);
+        const p = makeProcessRenderer(this.flags, "Port-forwarding a container");
+        const { host, user } = await getSSHConnectionForContainer(this.apiClient, serviceId, stackId, this.flags["ssh-user"]);
+        const portMappings = await this.getPortMappings(stackId, serviceId);
+        await p.complete(_jsxs(Box, { flexDirection: "column", children: [portMappings.map((p, idx) => (_jsxs(Text, { children: ["Forwarding container port ", _jsx(Value, { children: p.remotePort }), " to local port ", _jsx(Value, { children: p.localPort }), "."] }, idx))), _jsx(Text, { children: "Use CTRL+C to cancel." })] }));
+        const sshArgs = buildSSHClientFlags(user, host, this.flags, {
+            interactive: false,
+            additionalFlags: portMappings
+                .map((p) => ["-L", `${p.localPort}:localhost:${p.remotePort}`])
+                .flat(),
+        });
+        cp.spawnSync("ssh", [...sshArgs, "cat", "/dev/zero"], {
+            stdio: ["ignore", process.stdout, process.stderr],
+        });
+        return {};
+    }
+    async getPortMappings(stackId, serviceId) {
+        if (this.args.port) {
+            return [this.args.port];
+        }
+        const containerResponse = await this.apiClient.container.getService({
+            stackId,
+            serviceId,
+        });
+        assertStatus(containerResponse, 200);
+        const ports = containerResponse.data.deployedState.ports ?? [];
+        return ports.map((p) => PortMapping.fromPortAndProtocol(p));
+    }
+    render() {
+        return undefined;
+    }
+}

package/dist/commands/container/run.d.ts

@@ -5,6 +5,8 @@ type Result = {
 };
 export declare class Run extends ExecRenderBaseCommand<typeof Run, Result> {
     static summary: string;
+    static strict: boolean;
+    static usage: string;
     static flags: {
         env: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         "env-file": import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -24,6 +26,16 @@ export declare class Run extends ExecRenderBaseCommand<typeof Run, Result> {
     };
     protected exec(): Promise<Result>;
     private addServiceToStack;
+    /**
+     * Builds and returns the container command based on the provided image
+     * metadata and arguments.
+     *
+     * @param imageMeta The configuration object containing the metadata of the
+     *   container image, including the default command.
+     * @returns An array of strings representing the container command to execute,
+     *   or undefined if no specific command is set.
+     */
+    private buildContainerCommand;
     /**
      * Builds a container service request from command line arguments and image
      * metadata

package/dist/commands/container/run.js

@@ -3,13 +3,16 @@ import { Args, Flags } from "@oclif/core";
 import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
 import { makeProcessRenderer, processFlags, } from "../../rendering/process/process_flags.js";
 import { projectFlags } from "../../lib/resources/project/flags.js";
+import dockerNames from "docker-names";
+import { assertStatus } from "@mittwald/api-client";
+import { getImageMeta, getPortMappings, parseEnvironmentVariables, } from "../../lib/resources/container/containerconfig.js";
 import { Success } from "../../rendering/react/components/Success.js";
 import { Value } from "../../rendering/react/components/Value.js";
-import * as dockerNames from "docker-names";
-import { assertStatus } from "@mittwald/api-client";
-import { parseEnvironmentVariables, getPortMappings, getImageMeta, } from "../../lib/resources/container/containerconfig.js";
 export class Run extends ExecRenderBaseCommand {
     static summary = "Creates and starts a new container.";
+    static strict = false;
+    // Usage needs to be overwritten because the autogenerated one is incorrect due to the variadic arguments.
+    static usage = "container run [--token <value>] [-q] [-p <value>] [-e <value>...] [--env-file <value>...] [--description <value>] [--entrypoint <value>] [--name <value>] [-p <value>...] [-P] [-v <value>...] IMAGE [COMMAND] [ARGS...]";
     static flags = {
         ...processFlags,
         ...projectFlags,
@@ -45,11 +48,11 @@ export class Run extends ExecRenderBaseCommand {
             summary: "publish a container's port(s) to the host",
             description: "Map a container's port to a port on the host system. " +
                 "Format: <host-port>:<container-port> or just <container-port> (in which case the host port will be automatically assigned). " +
-                "For example, -p 8080:80 maps port 80 in the container to port 8080 on the host. " +
-                "Use multiple -p flags to publish multiple ports.",
+                "For example, --publish 8080:80 maps port 80 in the container to port 8080 on the host. " +
+                "Use multiple --publish flags to publish multiple ports.\n\n" +
+                "NOTE: Please note that the usual shorthand -p is not supported for this flag, as it would conflict with the --project flag.",
             required: false,
             multiple: true,
-            char: "p",
         }),
         "publish-all": Flags.boolean({
             summary: "publish all ports that are defined in the image",
@@ -85,7 +88,6 @@ export class Run extends ExecRenderBaseCommand {
             summary: "arguments to pass to the command",
             description: "These are the runtime arguments passed to the command specified by the command parameter or the container's default command, not to the container itself. For example, if the command is 'echo', the args might be 'hello world'.",
             required: false,
-            variadic: true,
         }),
     };
     async exec() {
@@ -116,6 +118,23 @@ export class Run extends ExecRenderBaseCommand {
         assertStatus(resp, 200);
         return resp.data;
     }
+    /**
+     * Builds and returns the container command based on the provided image
+     * metadata and arguments.
+     *
+     * @param imageMeta The configuration object containing the metadata of the
+     *   container image, including the default command.
+     * @returns An array of strings representing the container command to execute,
+     *   or undefined if no specific command is set.
+     */
+    buildContainerCommand(imageMeta) {
+        if (!this.args.command) {
+            return imageMeta.command;
+        }
+        const firstArg = (this.argv.lastIndexOf(this.args.command) ?? Infinity) + 1;
+        const command = [this.args.command, ...this.argv.slice(firstArg)];
+        return command;
+    }
     /**
      * Builds a container service request from command line arguments and image
      * metadata
@@ -126,7 +145,7 @@ export class Run extends ExecRenderBaseCommand {
      * @returns A properly formatted container service request
      */
     async buildServiceRequest(image, imageMeta, serviceName) {
-        const command = this.args.command ? [this.args.command] : imageMeta.command;
+        const command = this.buildContainerCommand(imageMeta);
         const entrypoint = this.flags.entrypoint
             ? [this.flags.entrypoint]
             : imageMeta.entrypoint;

package/dist/commands/container/ssh.d.ts

@@ -0,0 +1,17 @@
+import { ExtendedBaseCommand } from "../../lib/basecommands/ExtendedBaseCommand.js";
+export default class Ssh extends ExtendedBaseCommand<typeof Ssh> {
+    static summary: string;
+    static description: string;
+    static args: {
+        "container-id": import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        info: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        test: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        shell: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+        "ssh-user": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "ssh-identity-file": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/container/ssh.js

@@ -0,0 +1,61 @@
+import * as child_process from "child_process";
+import { Args, Flags } from "@oclif/core";
+import { ExtendedBaseCommand } from "../../lib/basecommands/ExtendedBaseCommand.js";
+import { getSSHConnectionForContainer } from "../../lib/resources/ssh/container.js";
+import { sshConnectionFlags, } from "../../lib/resources/ssh/flags.js";
+import { sshWrapperDocumentation } from "../../lib/resources/ssh/doc.js";
+import { buildSSHClientFlags } from "../../lib/resources/ssh/connection.js";
+import { withContainerAndStackId } from "../../lib/resources/container/flags.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+export default class Ssh extends ExtendedBaseCommand {
+    static summary = "Connect to a container via SSH";
+    static description = "Establishes an interactive SSH connection to a container.\n\n" +
+        sshWrapperDocumentation;
+    static args = {
+        "container-id": Args.string({
+            description: "ID or short ID of the container to connect to",
+            required: true,
+        }),
+    };
+    static flags = {
+        ...sshConnectionFlags,
+        ...projectFlags,
+        info: Flags.boolean({
+            summary: "only print connection information, without actually connecting",
+        }),
+        test: Flags.boolean({
+            summary: "test connection and exit",
+        }),
+        shell: Flags.string({
+            summary: "shell to use for the SSH connection",
+            default: "/bin/sh",
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Ssh);
+        const [containerId, stackId] = await withContainerAndStackId(this.apiClient, Ssh, flags, this.args, this.config);
+        const { host, user, directory } = await getSSHConnectionForContainer(this.apiClient, containerId, stackId, flags["ssh-user"]);
+        if (flags.info) {
+            this.log("hostname: %o", host);
+            this.log("username: %o", user);
+            this.log("directory: %o", directory);
+            return;
+        }
+        this.log("connecting to %o as %o", host, user);
+        const [cmd, args] = buildSSHCmdAndFlags(user, host, flags);
+        this.debug("running ssh %o, with command %o", args, cmd);
+        child_process.spawnSync("/usr/bin/ssh", [...args, cmd], {
+            stdio: "inherit",
+        });
+    }
+}
+function buildSSHCmdAndFlags(user, host, flags) {
+    const args = buildSSHClientFlags(user, host, flags, {
+        interactive: true,
+        additionalFlags: flags.test ? ["-q"] : [],
+    });
+    if (flags.test) {
+        return ["/bin/true", args];
+    }
+    return [flags.shell, args];
+}

package/dist/commands/domain/dnszone/update.js

@@ -6,6 +6,7 @@ import { Success } from "../../../rendering/react/components/Success.js";
 import { dnsZoneArgs, withDnsZoneId, } from "../../../lib/resources/domain/dnszone/flags.js";
 import { projectFlags } from "../../../lib/resources/project/flags.js";
 import { assertStatus } from "@mittwald/api-client-commons";
+import assertSuccess from "../../../lib/apiutil/assert_success.js";
 export default class Update extends ExecRenderBaseCommand {
     static description = "Updates a record set of a DNS zone";
     static args = {
@@ -163,9 +164,9 @@ export default class Update extends ExecRenderBaseCommand {
                 dnsZoneId,
                 recordSet,
             });
-            assertStatus(r, 204);
+            assertSuccess(r);
         });
-        process.complete(_jsx(Success, { children: "DNS record set successfully reset to fully managed." }));
+        await process.complete(_jsx(Success, { children: "DNS record set successfully reset to fully managed." }));
     }
     render() {
         return undefined;

package/dist/lib/basecommands/BaseCommand.js

@@ -5,6 +5,7 @@ import { CoreBaseCommand } from "./CoreBaseCommand.js";
 import { configureAxiosLogging } from "../apiutil/api_logging.js";
 import { configureAxiosRetry } from "../apiutil/api_retry.js";
 import { configureConsistencyHandling } from "../apiutil/api_consistency.js";
+import NoTokenFoundError from "../error/NoTokenFoundError.js";
 /** Base command class for authenticated commands that includes the --token flag. */
 export class BaseCommand extends CoreBaseCommand {
     static baseFlags = {
@@ -21,7 +22,7 @@ export class BaseCommand extends CoreBaseCommand {
             const { flags } = await this.parse();
             const token = await this.getEffectiveTokenWithFlag(flags);
             if (token === undefined) {
-                throw new Error(`Could not get token from --token flag, MITTWALD_API_TOKEN env var, or config file (${getTokenFilename(this.config)}). Please run "mw login token" or use --token.`);
+                throw new NoTokenFoundError(getTokenFilename(this.config));
             }
             this.apiClient = MittwaldAPIV2Client.newWithToken(token);
             this.apiClient.axios.defaults.headers["User-Agent"] =

package/dist/lib/error/NoTokenFoundError.d.ts

@@ -0,0 +1,11 @@
+/**
+ * This class represents a custom error thrown when no token can be found. The
+ * error specifically occurs if the token is not provided via the --token flag,
+ * the MITTWALD_API_TOKEN environment variable, or the configuration file.
+ *
+ * This is a dedicated error class so that the error handler can check for this
+ * specific type of error and present it differently to the user.
+ */
+export default class NoTokenFoundError extends Error {
+    constructor(tokenFilename: string);
+}

package/dist/lib/error/NoTokenFoundError.js

@@ -0,0 +1,13 @@
+/**
+ * This class represents a custom error thrown when no token can be found. The
+ * error specifically occurs if the token is not provided via the --token flag,
+ * the MITTWALD_API_TOKEN environment variable, or the configuration file.
+ *
+ * This is a dedicated error class so that the error handler can check for this
+ * specific type of error and present it differently to the user.
+ */
+export default class NoTokenFoundError extends Error {
+    constructor(tokenFilename) {
+        super(`Could not get token from --token flag, MITTWALD_API_TOKEN env var, or config file (${tokenFilename}). Please run "mw login token" or use --token.`);
+    }
+}

package/dist/lib/resources/ssh/container.d.ts

@@ -0,0 +1,3 @@
+import { MittwaldAPIV2Client } from "@mittwald/api-client";
+import { SSHConnectionData } from "./types.js";
+export declare function getSSHConnectionForContainer(client: MittwaldAPIV2Client, containerId: string, stackId: string, sshUser: string | undefined): Promise<SSHConnectionData>;

package/dist/lib/resources/ssh/container.js

@@ -0,0 +1,29 @@
+import { assertStatus } from "@mittwald/api-client";
+export async function getSSHConnectionForContainer(client, containerId, stackId, sshUser) {
+    // Get container details
+    const containerResponse = await client.container.getService({
+        stackId,
+        serviceId: containerId,
+    });
+    assertStatus(containerResponse, 200);
+    // Get project details
+    const projectResponse = await client.project.getProject({
+        projectId: containerResponse.data.projectId,
+    });
+    assertStatus(projectResponse, 200);
+    // If no SSH user is provided, use the current user's email
+    if (sshUser === undefined) {
+        const userResponse = await client.user.getUser({ userId: "self" });
+        assertStatus(userResponse, 200);
+        sshUser = userResponse.data.email;
+    }
+    // Construct the SSH connection data
+    const host = `ssh.${projectResponse.data.clusterID}.${projectResponse.data.clusterDomain}`;
+    const user = `${sshUser}@${containerResponse.data.shortId}`;
+    const directory = "/";
+    return {
+        host,
+        user,
+        directory,
+    };
+}

package/dist/lib/units/PortMapping.d.ts

@@ -0,0 +1,11 @@
+/** Represents a mapping between a local port and a remote port. */
+export default class PortMapping {
+    readonly localPort: number;
+    readonly remotePort: number;
+    constructor(localPort: number, remotePort: number);
+    private static validatePort;
+    static arg: import("@oclif/core/interfaces").ArgDefinition<PortMapping, Record<string, unknown>>;
+    /** @param str Port and protocol; example: `8080/tcp` */
+    static fromPortAndProtocol(str: string): PortMapping;
+    static fromString(str: string): PortMapping;
+}

package/dist/lib/units/PortMapping.js

@@ -0,0 +1,38 @@
+import { Args } from "@oclif/core";
+/** Represents a mapping between a local port and a remote port. */
+export default class PortMapping {
+    localPort;
+    remotePort;
+    constructor(localPort, remotePort) {
+        this.localPort = localPort;
+        this.remotePort = remotePort;
+    }
+    static validatePort(port) {
+        return !isNaN(port) && port > 0 && port <= 65535;
+    }
+    static arg = Args.custom({
+        parse: async (input) => PortMapping.fromString(input),
+    });
+    /** @param str Port and protocol; example: `8080/tcp` */
+    static fromPortAndProtocol(str) {
+        const [localPort, protocol] = str.split("/");
+        const portNum = parseInt(localPort);
+        if (!PortMapping.validatePort(portNum)) {
+            throw new Error("Invalid port number. Ports must be between 1 and 65535.");
+        }
+        if (protocol.toLowerCase() !== "tcp") {
+            throw new Error("Only TCP protocol is supported.");
+        }
+        return new PortMapping(portNum, portNum);
+    }
+    static fromString(str) {
+        const [localPort, remotePort] = str.split(":");
+        const localPortNum = parseInt(localPort);
+        const remotePortNum = parseInt(remotePort);
+        if (!PortMapping.validatePort(localPortNum) ||
+            !PortMapping.validatePort(remotePortNum)) {
+            throw new Error("Invalid port number. Ports must be between 1 and 65535.");
+        }
+        return new PortMapping(localPortNum, remotePortNum);
+    }
+}

package/dist/lib/units/PortMapping.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/units/PortMapping.test.js

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "@jest/globals";
+import PortMapping from "./PortMapping.js";
+describe("PortMapping", () => {
+    // Test: Successfully create PortMapping instance using fromString
+    it("should correctly parse valid port mapping string", () => {
+        const result = PortMapping.fromString("8080:9090");
+        expect(result.localPort).toBe(8080);
+        expect(result.remotePort).toBe(9090);
+    });
+    // Test: Throws an error for invalid local port
+    it("should throw an error for invalid local port", () => {
+        expect(() => PortMapping.fromString("100000:8080")).toThrow("Invalid port number. Ports must be between 1 and 65535.");
+    });
+    // Test: Throws an error for invalid remote port
+    it("should throw an error for invalid remote port", () => {
+        expect(() => PortMapping.fromString("8080:70000")).toThrow("Invalid port number. Ports must be between 1 and 65535.");
+    });
+    // Test: Throws an error when input format is incorrect
+    it("should throw an error for invalid string format", () => {
+        expect(() => PortMapping.fromString("8080-9090")).toThrow("Invalid port number. Ports must be between 1 and 65535.");
+    });
+    // Test: Successfully assign local and remote ports via constructor
+    it("should correctly initialize PortMapping with valid ports", () => {
+        const portMapping = new PortMapping(3000, 4000);
+        expect(portMapping.localPort).toBe(3000);
+        expect(portMapping.remotePort).toBe(4000);
+    });
+});

package/dist/rendering/react/components/ErrorBox.js

@@ -6,6 +6,7 @@ import GenericError from "./Error/GenericError.js";
 import APIError from "./Error/APIError.js";
 import UnexpectedShortIDPassedErrorBox from "./Error/UnexpectedShortIDPassedErrorBox.js";
 import { MissingArgError, MissingFlagError, } from "../../../lib/context/FlagSetBuilder.js";
+import NoTokenFoundError from "../../../lib/error/NoTokenFoundError.js";
 /**
  * Render an error to the terminal.
  *
@@ -27,6 +28,9 @@ export const ErrorBox = ({ err }) => {
         err instanceof MissingFlagError) {
         return (_jsx(GenericError, { err: err, withStack: false, withIssue: false, title: "Input required" }));
     }
+    else if (err instanceof NoTokenFoundError) {
+        return (_jsx(GenericError, { err: err, withStack: false, withIssue: false, title: "Login required" }));
+    }
     else if (err instanceof UnexpectedShortIDPassedError) {
         return _jsx(UnexpectedShortIDPassedErrorBox, { err: err });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/cli",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Hand-crafted CLI for the mittwald API",
   "license": "MIT",
   "author": {
@@ -68,7 +68,7 @@
     "semver-parser": "^4.1.6",
     "shell-escape": "^0.2.0",
     "slice-ansi": "^7.1.0",
-    "string-width": "^7.2.0",
+    "string-width": "^8.0.0",
     "tempfile": "^5.0.0",
     "uuid": "^11.0.3"
   },
@@ -94,7 +94,7 @@
     "oclif": "^4.14.31",
     "prettier": "~3.6.2",
     "prettier-plugin-jsdoc": "^1.3.2",
-    "prettier-plugin-package": "^1.4.0",
+    "prettier-plugin-package": "^2.0.0",
     "prettier-plugin-sort-json": "^4.1.1",
     "rimraf": "^5.0.1",
     "ts-jest": "^29.2.5",
@@ -117,6 +117,9 @@
       "app": {
         "description": "Manage apps, and app installations in your projects",
         "subtopics": {
+          "create": {
+            "description": "Create new self-managed apps in your projects"
+          },
           "install": {
             "description": "Install apps in your projects"
           },
@@ -128,9 +131,6 @@
       "registry": {
         "description": "Manage container registries"
       },
-      "article": {
-        "description": "Query available hosting articles"
-      },
       "backup": {
         "description": "Manage backups of your projects",
         "subtopics": {
@@ -139,12 +139,12 @@
           }
         }
       },
+      "container": {
+        "description": "Manage containers"
+      },
       "context": {
         "description": "Save certain environment parameters for later use"
       },
-      "contract": {
-        "description": "Manage your hosting contracts, and order new ones"
-      },
       "conversation": {
         "description": "Manage your support cases"
       },
@@ -157,16 +157,42 @@
         }
       },
       "cronjob": {
-        "description": "Manage cronjobs of your projects"
+        "description": "Manage cronjobs of your projects",
+        "subtopics": {
+          "execution": {
+            "description": "Manage individual cronjob executions"
+          }
+        }
       },
       "database": {
-        "description": "Manage databases (like MySQL and Redis) in your projects"
+        "description": "Manage databases (like MySQL and Redis) in your projects",
+        "subtopics": {
+          "mysql": {
+            "description": "Manage MySQL databases in your projects",
+            "subtopics": {
+              "user": {
+                "description": "Manage MySQL database users"
+              }
+            }
+          },
+          "redis": {
+            "description": "Manage Redis databases in your projects"
+          }
+        }
       },
       "ddev": {
         "description": "Integrate your mittwald projects with DDEV"
       },
       "domain": {
-        "description": "Manage domains, virtual hosts and DNS settings in your projects"
+        "description": "Manage domains, virtual hosts and DNS settings in your projects",
+        "subtopics": {
+          "dnszone": {
+            "description": "Manage DNS zones for your domains"
+          },
+          "virtualhost": {
+            "description": "Manage virtual hosts for your domains"
+          }
+        }
       },
       "extension": {
         "description": "Install and manage extensions in your organisations and projects"
@@ -175,10 +201,26 @@
         "description": "Manage your client authentication"
       },
       "mail": {
-        "description": "Manage mailboxes and mail addresses in your projects"
+        "description": "Manage mailboxes and mail addresses in your projects",
+        "subtopics": {
+          "address": {
+            "description": "Manage mail addresses in your projects"
+          },
+          "deliverybox": {
+            "description": "Manage mail delivery boxes in your projects"
+          }
+        }
       },
       "org": {
-        "description": "Manage your organizations, and also any kinds of user memberships concerning these organizations."
+        "description": "Manage your organizations, and also any kinds of user memberships concerning these organizations.",
+        "subtopics": {
+          "invite": {
+            "description": "Invite users to your organizations and manage their invitations"
+          },
+          "membership": {
+            "description": "Control who gets to work in your organizations, and who doesn't"
+          }
+        }
       },
       "project": {
         "description": "Manage your projects, and also any kinds of user memberships concerning these projects.",
@@ -209,6 +251,12 @@
       "user": {
         "description": "Manage your own user account",
         "subtopics": {
+          "api-token": {
+            "description": "Manage your API tokens"
+          },
+          "session": {
+            "description": "Manage your active sessions"
+          },
           "ssh-key": {
             "description": "Manage your SSH keys"
           }