@mittwald/cli 1.8.1 → 1.9.0

package/README.md

@@ -127,5 +127,6 @@ USAGE
 * [`mw stack`](docs/stack.md) - Manage container stacks
 * [`mw update`](docs/update.md) - update the mw CLI
 * [`mw user`](docs/user.md) - Manage your own user account
+* [`mw volume`](docs/volume.md) - Manage volumes
 
 <!-- commandsstop -->

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

@@ -16,6 +16,7 @@ export declare class Run extends ExecRenderBaseCommand<typeof Run, Result> {
         publish: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         "publish-all": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         volume: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "create-volumes": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
         quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
@@ -26,6 +27,13 @@ export declare class Run extends ExecRenderBaseCommand<typeof Run, Result> {
     };
     protected exec(): Promise<Result>;
     private addServiceToStack;
+    /**
+     * Gets the list of named volumes that need to be created.
+     *
+     * @param stackId The stack ID to check existing volumes against
+     * @returns Array of volume names that need to be created
+     */
+    private getVolumesToCreate;
     /**
      * Builds and returns the container command based on the provided image
      * metadata and arguments.

package/dist/commands/container/run.js

@@ -21,12 +21,14 @@ export class Run extends ExecRenderBaseCommand {
             description: "Format: KEY=VALUE. Multiple environment variables can be specified with multiple --env flags.",
             required: false,
             multiple: true,
+            multipleNonGreedy: true,
             char: "e",
         }),
         "env-file": Flags.string({
             summary: "read environment variables from a file",
             description: "The file should contain lines in the format KEY=VALUE. Multiple files can be specified with multiple --env-file flags.",
             multiple: true,
+            multipleNonGreedy: true,
             required: false,
         }),
         description: Flags.string({
@@ -53,6 +55,7 @@ export class Run extends ExecRenderBaseCommand {
                 "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,
+            multipleNonGreedy: true,
         }),
         "publish-all": Flags.boolean({
             summary: "publish all ports that are defined in the image",
@@ -71,6 +74,13 @@ export class Run extends ExecRenderBaseCommand {
             required: false,
             char: "v",
             multiple: true,
+            multipleNonGreedy: true,
+        }),
+        "create-volumes": Flags.boolean({
+            summary: "automatically create named volumes that do not exist",
+            description: "When enabled, any named volumes referenced in --volume flags that do not already exist will be automatically created before starting the container.",
+            required: false,
+            default: false,
         }),
     };
     static args = {
@@ -107,17 +117,52 @@ export class Run extends ExecRenderBaseCommand {
         return { serviceId };
     }
     async addServiceToStack(stackId, serviceName, serviceRequest) {
+        const updateData = {
+            services: {
+                [serviceName]: serviceRequest,
+            },
+        };
+        // If create-volumes flag is enabled, add missing volumes to the same call
+        if (this.flags["create-volumes"] && this.flags.volume) {
+            const volumesToCreate = await this.getVolumesToCreate(stackId);
+            if (volumesToCreate.length > 0) {
+                updateData.volumes = Object.fromEntries(volumesToCreate.map((name) => [name, { name }]));
+            }
+        }
         const resp = await this.apiClient.container.updateStack({
             stackId,
-            data: {
-                services: {
-                    [serviceName]: serviceRequest,
-                },
-            },
+            data: updateData,
         });
         assertStatus(resp, 200);
         return resp.data;
     }
+    /**
+     * Gets the list of named volumes that need to be created.
+     *
+     * @param stackId The stack ID to check existing volumes against
+     * @returns Array of volume names that need to be created
+     */
+    async getVolumesToCreate(stackId) {
+        if (!this.flags.volume) {
+            return [];
+        }
+        // Get current stack state to check existing volumes
+        const currentStackResp = await this.apiClient.container.getStack({
+            stackId,
+        });
+        assertStatus(currentStackResp, 200);
+        const existingVolumes = (currentStackResp.data.volumes || []).map((v) => v.name);
+        // Parse volume flags to extract named volumes (not file paths)
+        const namedVolumes = new Set(this.flags.volume
+            .filter((volume) => {
+            const [source] = volume.split(":");
+            // Named volumes typically don't start with /
+            return source && !source.startsWith("/");
+        })
+            .map((volume) => volume.split(":")[0]));
+        // Find volumes that need to be created
+        return Array.from(namedVolumes).filter((volumeName) => !existingVolumes.includes(volumeName));
+    }
     /**
      * Builds and returns the container command based on the provided image
      * metadata and arguments.
@@ -150,7 +195,7 @@ export class Run extends ExecRenderBaseCommand {
             ? [this.flags.entrypoint]
             : imageMeta.entrypoint;
         const description = this.flags.description ?? serviceName;
-        const envs = await parseEnvironmentVariables(this.flags.env, this.flags["env-file"]);
+        const environment = await parseEnvironmentVariables(this.flags.env, this.flags["env-file"]);
         const ports = getPortMappings(imageMeta, this.flags["publish-all"], this.flags.publish);
         const volumes = this.flags.volume;
         return {
@@ -158,7 +203,7 @@ export class Run extends ExecRenderBaseCommand {
             command,
             entrypoint,
             description,
-            envs,
+            environment,
             ports,
             volumes,
         };

package/dist/commands/volume/create.d.ts

@@ -0,0 +1,20 @@
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import { ReactNode } from "react";
+type Result = {
+    volumeName: string;
+    stackId: string;
+};
+export declare class Create extends ExecRenderBaseCommand<typeof Create, Result> {
+    static summary: string;
+    static description: string;
+    static flags: {
+        quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+    };
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    protected exec(): Promise<Result>;
+    protected render({ volumeName }: Result): ReactNode;
+}
+export {};

package/dist/commands/volume/create.js

@@ -0,0 +1,57 @@
+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 { Args } from "@oclif/core";
+import { assertStatus } from "@mittwald/api-client-commons";
+import { Success } from "../../rendering/react/components/Success.js";
+import { Value } from "../../rendering/react/components/Value.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+export class Create extends ExecRenderBaseCommand {
+    static summary = "Create a new volume";
+    static description = "Creates a new named volume in the project stack. The volume will be available for use by containers.";
+    static flags = {
+        ...projectFlags,
+        ...processFlags,
+    };
+    static args = {
+        name: Args.string({
+            description: "name of the volume to create",
+            required: true,
+        }),
+    };
+    async exec() {
+        const process = makeProcessRenderer(this.flags, "Creating a new volume");
+        const projectId = await this.withProjectId(Create);
+        const stackId = projectId; // In mStudio, project and stack are the same for volumes
+        const { name: volumeName } = this.args;
+        // Get current stack state
+        const currentStack = await process.runStep("getting current stack state", async () => {
+            const r = await this.apiClient.container.getStack({ stackId });
+            assertStatus(r, 200);
+            return r.data;
+        });
+        // Check if volume already exists
+        if ((currentStack.volumes || []).some((v) => v.name === volumeName)) {
+            throw new Error(`Volume "${volumeName}" already exists`);
+        }
+        // Update stack to include the new volume
+        await process.runStep("creating volume", async () => {
+            const r = await this.apiClient.container.updateStack({
+                stackId,
+                data: {
+                    volumes: {
+                        [volumeName]: { name: volumeName },
+                    },
+                },
+            });
+            assertStatus(r, 200);
+        });
+        await process.complete(_jsxs(Success, { children: ["Volume ", _jsx(Value, { children: volumeName }), " was successfully created."] }));
+        return { volumeName, stackId };
+    }
+    render({ volumeName }) {
+        if (this.flags.quiet) {
+            return volumeName;
+        }
+    }
+}

package/dist/commands/volume/delete.d.ts

@@ -0,0 +1,22 @@
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import { ReactNode } from "react";
+type Result = {
+    volumeName: string;
+};
+export declare class Delete extends ExecRenderBaseCommand<typeof Delete, Result> {
+    static summary: string;
+    static description: string;
+    static aliases: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+    };
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    protected exec(): Promise<Result>;
+    private checkVolumeInUse;
+    protected render({ volumeName }: Result): ReactNode;
+}
+export {};

package/dist/commands/volume/delete.js

@@ -0,0 +1,89 @@
+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 { Args, Flags } from "@oclif/core";
+import { assertStatus } from "@mittwald/api-client-commons";
+import { Success } from "../../rendering/react/components/Success.js";
+import { Value } from "../../rendering/react/components/Value.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+export class Delete extends ExecRenderBaseCommand {
+    static summary = "Remove one or more volumes";
+    static description = "Removes named volumes from the project stack. Be careful as this will permanently delete the volume data.";
+    static aliases = ["volume:rm"];
+    static flags = {
+        ...projectFlags,
+        ...processFlags,
+        force: Flags.boolean({
+            summary: "force removal without confirmation",
+            char: "f",
+            default: false,
+        }),
+    };
+    static args = {
+        name: Args.string({
+            description: "name of the volume to remove",
+            required: true,
+        }),
+    };
+    async exec() {
+        const process = makeProcessRenderer(this.flags, "Removing volume");
+        const projectId = await this.withProjectId(Delete);
+        const stackId = projectId; // In mStudio, project and stack are the same for volumes
+        const { name: volumeName } = this.args;
+        // Get current stack state
+        const currentStack = await process.runStep("getting current stack state", async () => {
+            const r = await this.apiClient.container.getStack({ stackId });
+            assertStatus(r, 200);
+            return r.data;
+        });
+        // Check if volume exists
+        if (!(currentStack.volumes || []).some((v) => v.name === volumeName)) {
+            throw new Error(`Volume "${volumeName}" does not exist`);
+        }
+        // Check if volume is in use by any services
+        const volumeInUse = this.checkVolumeInUse(currentStack.services, volumeName);
+        if (volumeInUse && !this.flags.force) {
+            throw new Error(`Volume "${volumeName}" is in use by one or more containers. Use --force to remove anyway.`);
+        }
+        // Delete the actual volume data if it exists
+        await process.runStep("deleting volume", async () => {
+            const volumesResponse = await this.apiClient.container.listVolumes({
+                projectId,
+            });
+            assertStatus(volumesResponse, 200);
+            const volume = volumesResponse.data.find((v) => v.name === volumeName && v.stackId === stackId);
+            if (volume) {
+                const deleteResponse = await this.apiClient.container.deleteVolume({
+                    stackId,
+                    volumeId: volume.id,
+                });
+                assertStatus(deleteResponse, 204);
+            }
+        });
+        await process.complete(_jsxs(Success, { children: ["Volume ", _jsx(Value, { children: volumeName }), " was successfully removed."] }));
+        return { volumeName };
+    }
+    checkVolumeInUse(services, volumeName) {
+        if (!services) {
+            return false;
+        }
+        for (const service of services) {
+            const volumes = service.deployedState?.volumes;
+            if (volumes) {
+                for (const volumeMount of volumes) {
+                    // Check if this is a named volume (not a bind mount)
+                    if (volumeMount.includes(":") &&
+                        volumeMount.split(":")[0] === volumeName) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    render({ volumeName }) {
+        if (this.flags.quiet) {
+            return volumeName;
+        }
+    }
+}

package/dist/commands/volume/list.d.ts

@@ -0,0 +1,24 @@
+import { Simplify } from "@mittwald/api-client-commons";
+import { MittwaldAPIV2, MittwaldAPIV2Client } from "@mittwald/api-client";
+import { ListBaseCommand } from "../../lib/basecommands/ListBaseCommand.js";
+import { ListColumns } from "../../rendering/formatter/Table.js";
+type ResponseItem = Simplify<MittwaldAPIV2.Paths.V2ProjectsProjectIdVolumes.Get.Responses.$200.Content.ApplicationJson[number]>;
+type Response = Awaited<ReturnType<MittwaldAPIV2Client["container"]["listVolumes"]>>;
+export declare class List extends ListBaseCommand<typeof List, ResponseItem, Response> {
+    static description: string;
+    static aliases: string[];
+    static args: {};
+    static flags: {
+        "project-id": import("@oclif/core/interfaces").OptionFlag<string>;
+        output: import("@oclif/core/interfaces").OptionFlag<"json" | "txt" | "yaml" | "csv" | "tsv">;
+        extended: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-header": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-truncate": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-relative-dates": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "csv-separator": import("@oclif/core/interfaces").OptionFlag<"," | ";">;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    getData(): Promise<Response>;
+    protected getColumns(data: ResponseItem[]): ListColumns<ResponseItem>;
+}
+export {};

package/dist/commands/volume/list.js

@@ -0,0 +1,51 @@
+import { ListBaseCommand } from "../../lib/basecommands/ListBaseCommand.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+import { makeDateRendererForFormat } from "../../rendering/textformat/formatDate.js";
+import ByteQuantity from "../../lib/units/ByteQuantity.js";
+export class List extends ListBaseCommand {
+    static description = "List volumes belonging to a project.";
+    static aliases = ["volume:ls"];
+    static args = {};
+    static flags = {
+        ...ListBaseCommand.baseFlags,
+        ...projectFlags,
+    };
+    async getData() {
+        const projectId = await this.withProjectId(List);
+        return this.apiClient.container.listVolumes({ projectId });
+    }
+    getColumns(data) {
+        const { id } = super.getColumns(data);
+        const dateFormatter = makeDateRendererForFormat(this.flags.output, !this.flags["no-relative-dates"]);
+        return {
+            id: {
+                ...id,
+                extended: true,
+            },
+            name: {
+                get: (volume) => volume.name,
+            },
+            stackId: {
+                header: "Stack",
+                extended: true,
+                exactWidth: 40,
+            },
+            usedIn: {
+                header: "Used in",
+                get: (volume) => {
+                    if (volume.orphaned) {
+                        return "orphaned";
+                    }
+                    return (volume.linkedServices ?? []).length + " services";
+                },
+            },
+            storageUsage: {
+                header: "Size",
+                get: (volume) => ByteQuantity.fromBytes(volume.storageUsageInBytes).format() +
+                    " (updated " +
+                    dateFormatter(volume.storageUsageInBytesSetAt) +
+                    ")",
+            },
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/cli",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Hand-crafted CLI for the mittwald API",
   "license": "MIT",
   "author": {
@@ -261,6 +261,9 @@
             "description": "Manage your SSH keys"
           }
         }
+      },
+      "volume": {
+        "description": "Manage volumes"
       }
     },
     "plugins": [