@cloud-cli/vm 1.3.1 → 1.4.0

package/.github/workflows/cicd.yml

@@ -1,13 +1,10 @@
 name: CICD
 on:
-  push:
-    branches:
-      - main
+  - push
+
 jobs:
   release:
-    uses: homebots/workflows/.github/workflows/node-build-release.yml@master
-    with:
-      branches: main
+    uses: cloud-cli/workflows/.github/workflows/npm-build-release.yml@main
     secrets:
       NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-interface NameOption {
+import { help } from "@cloud-cli/cli";
+interface Options {
+    _?: string[];
+}
+interface NameOption extends Options {
     name: string;
 }
-interface NameAndPathOption {
+interface NameAndPathOption extends Options {
     name: string;
     path?: string;
 }
@@ -28,5 +32,6 @@ declare const _default: {
     rm: typeof rm;
     cat: typeof cat;
     fixPermissions: typeof fixPermissions;
+    [help]: () => string;
 };
 export default _default;

package/dist/index.js

@@ -1,61 +1,70 @@
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
-import { exec } from '@cloud-cli/exec';
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { exec } from "@cloud-cli/exec";
+import { help } from "@cloud-cli/cli";
 const nameRe = /^[a-z][a-z0-9-]+$/;
 const isValidName = (name) => nameRe.test(name);
-const invalidNameError = new Error('Invalid name');
+const invalidNameError = new Error("Invalid name");
+const readOptions = (options) => {
+    options.name || (options.name = options._?.[0]);
+    if (!isValidName(options.name)) {
+        throw invalidNameError;
+    }
+};
 async function list() {
-    const output = await exec('docker', ['volume', 'ls', '--format={{.Name}}']);
+    const output = await exec("docker", ["volume", "ls", "--format={{.Name}}"]);
     if (!output.ok) {
-        throw new Error('Unable to list volumes');
+        throw new Error("Unable to list volumes");
     }
-    return output.stdout.trim().split('\n');
+    return output.stdout.trim().split("\n");
 }
 async function getVolumeMountpoint(name) {
-    const output = await exec('docker', ['volume', 'inspect', name]);
+    const output = await exec("docker", ["volume", "inspect", name]);
     const volumes = JSON.parse(output.stdout);
     if (!volumes.length) {
-        throw new Error('Volume not found');
+        throw new Error("Volume not found");
     }
     return volumes[0].Mountpoint;
 }
 async function ls(options) {
-    const { name, path = '' } = options;
+    readOptions(options);
+    const { name, path = "" } = options;
     const root = await getVolumeMountpoint(name);
-    const files = await exec('ls', ['-1', join(root, path)]);
-    return files.stdout.trim().split('\n').filter(Boolean);
+    const files = await exec("ls", ["-1", join(root, path)]);
+    return files.stdout.trim().split("\n").filter(Boolean);
 }
 async function fixPermissions(options) {
+    readOptions(options);
     const { name } = options;
     const root = await getVolumeMountpoint(name);
-    const result = await exec('chmod', ['-R', 'a+w', root]);
+    const result = await exec("chmod", ["-R", "a+w", root]);
     return result.ok;
 }
 async function rm(options) {
+    readOptions(options);
     const { name, path } = options;
     if (!path) {
-        throw new Error('Path not specified');
+        throw new Error("Path not specified");
     }
     const root = await getVolumeMountpoint(name);
-    const result = await exec('rm', ['-r', join(root, path)]);
+    const result = await exec("rm", ["-r", join(root, path)]);
     return result.ok;
 }
 async function cat(options) {
+    readOptions(options);
     const { name, path } = options;
     if (!path) {
-        throw new Error('Path not specified');
+        throw new Error("Path not specified");
     }
     const root = await getVolumeMountpoint(name);
-    return await readFile(join(root, path), 'utf8');
+    return await readFile(join(root, path), "utf8");
 }
 async function show(options) {
-    if (!isValidName(options.name)) {
-        throw invalidNameError;
-    }
-    const output = await exec('docker', ['volume', 'inspect', options.name]);
+    readOptions(options);
+    const output = await exec("docker", ["volume", "inspect", options.name]);
     const list = JSON.parse(output.stdout);
     if (!list.length) {
-        throw new Error('Volume not found');
+        throw new Error("Volume not found");
     }
     const { Name, Labels, CreatedAt } = list[0];
     return {
@@ -65,27 +74,50 @@ async function show(options) {
     };
 }
 async function add(options) {
-    if (!isValidName(options.name)) {
-        throw invalidNameError;
-    }
-    const output = await exec('docker', ['volume', 'create', options.name]);
+    readOptions(options);
+    const output = await exec("docker", ["volume", "create", options.name]);
     if (output.ok) {
+        await fixPermissions(options);
         return true;
     }
-    throw new Error('Unable to create volume');
+    throw new Error("Unable to create volume");
 }
 async function remove(options) {
-    if (!isValidName(options.name)) {
-        throw invalidNameError;
-    }
-    const output = await exec('docker', ['volume', 'rm', options.name]);
+    readOptions(options);
+    const output = await exec("docker", ["volume", "rm", options.name]);
     if (output.ok) {
         return true;
     }
-    throw new Error('Unable to remove volume');
+    throw new Error("Unable to remove volume");
 }
 async function prune() {
-    await exec('docker', ['volume', 'prune']);
-    return '';
+    await exec("docker", ["volume", "prune"]);
+    return "";
 }
-export default { add, remove, list, show, prune, ls, rm, cat, fixPermissions };
+export default {
+    add,
+    remove,
+    list,
+    show,
+    prune,
+    ls,
+    rm,
+    cat,
+    fixPermissions,
+    [help]: () => `Manage Docker volumes
+
+Available commands:
+  vm.add --name <name> - Create a new Docker volume (name must be lowercase alphanumeric with hyphens)
+  vm.remove --name <name> - Remove a Docker volume
+  vm.list - List all Docker volumes
+  vm.ls --name <name> [--path <path>] - List files in a volume
+  vm.cat --name <name> --path <path> - Read a file from a volume
+  vm.show --name <name> - Show volume details
+  vm.fixPermissions --name <name> - Fix permissions on a volume
+  vm.rm --name <name> --path <path> - Remove a file or directory from a volume
+  vm.prune - Remove all unused Docker volumes
+
+Options:
+  name - Volume name (lowercase alphanumeric with hyphens)
+  path - Path within the volume`,
+};

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@cloud-cli/vm",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Docker volume management",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "type": "module",
   "prettier": "@cloud-cli/prettier-config",
   "scripts": {
-    "test": "jest",
-    "tdd": "jest --watchAll",
+    "test": "vitest",
     "build": "tsc"
   },
   "keywords": [
@@ -24,11 +23,16 @@
   "author": "Darlan Alves <me@darlanalv.es>",
   "license": "MIT",
   "devDependencies": {
-    "@cloud-cli/jest-config": "^1.0.0",
     "@cloud-cli/prettier-config": "^1.0.0",
-    "@cloud-cli/typescript-config": "^1.0.1"
+    "@cloud-cli/typescript-config": "^1.0.1",
+    "@types/node": "^20.19.43",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
   },
   "dependencies": {
     "@cloud-cli/exec": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@cloud-cli/cli": "^2.2.0"
   }
 }

package/src/index.spec.ts

@@ -1,17 +1,22 @@
-const execMocks = {
-  exec: jest.fn(),
-};
-
-const fsMocks = {
-  readFile: jest.fn(),
-};
-
-jest.mock('@cloud-cli/exec', () => execMocks);
-jest.mock('node:fs/promises', () => fsMocks);
-
-import vm from './index';
-import * as exec from '@cloud-cli/exec';
-import * as fs from 'node:fs/promises';
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { help } from "@cloud-cli/cli";
+import vm from "./index";
+
+const execMocks = vi.hoisted(() => ({
+  exec: vi.fn(),
+  readFile: vi.fn(),
+}));
+
+vi.mock("get-port", () => ({ default: vi.fn().mockReturnValue(1234) }));
+vi.mock("@cloud-cli/exec", () => ({ exec: execMocks.exec }));
+vi.mock("node:fs/promises", () => ({ readFile: execMocks.readFile }));
+vi.mock("@cloud-cli/cli", async (importOriginal) => {
+  const mod: any = await importOriginal();
+  return {
+    ...mod,
+    help: mod.help,
+  };
+});
 
 const inspectOutput = `[{
 "CreatedAt": "2023-03-10T10:15:10Z",
@@ -26,191 +31,217 @@ const inspectOutput = `[{
 "Scope": "local"
 }]`;
 
-describe('volume manager', () => {
-  describe('list', () => {
-    it('should list the available volumes', async () => {
+describe("help", () => {
+  it("should have a [help] Symbol export that is a function", () => {
+    expect(vm[help]).toBeDefined();
+    expect(typeof vm[help]).toBe("function");
+  });
+
+  it("should return a string help text", () => {
+    const helpText = vm[help]();
+    expect(typeof helpText).toBe("string");
+    expect(helpText).toContain("Docker");
+    expect(helpText).toContain("vm.add");
+    expect(helpText).toContain("vm.remove");
+    expect(helpText).toContain("vm.list");
+    expect(helpText).toContain("vm.ls");
+    expect(helpText).toContain("vm.cat");
+    expect(helpText).toContain("vm.show");
+    expect(helpText).toContain("vm.fixPermissions");
+    expect(helpText).toContain("vm.rm");
+    expect(helpText).toContain("vm.prune");
+  });
+
+  it('should not expose "help" as a normal command key', () => {
+    expect(Object.hasOwn(vm, "help")).toBe(false);
+  });
+});
+
+describe("volume manager", () => {
+  beforeEach(() => {
+    execMocks.exec.mockReset();
+    execMocks.readFile.mockReset();
+  });
+
+  describe("list", () => {
+    it("should list the available volumes", async () => {
       const execOutput = {
         ok: true,
         stdout: `test\ntest2\n`,
       };
 
-      execMocks.exec = jest.fn().mockResolvedValue(execOutput);
+      execMocks.exec.mockResolvedValue(execOutput);
 
-      await expect(vm.list()).resolves.toEqual(['test', 'test2']);
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'ls', '--format={{.Name}}']);
+      await expect(vm.list()).resolves.toEqual(["test", "test2"]);
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "ls", "--format={{.Name}}"]);
     });
 
-    it('should reject in case of error', async () => {
+    it("should reject in case of error", async () => {
       const output = { ok: false };
-      execMocks.exec = jest.fn().mockResolvedValue(output);
+      execMocks.exec.mockResolvedValue(output);
 
-      await expect(vm.list()).rejects.toThrowError('Unable to list volumes');
+      await expect(vm.list()).rejects.toThrowError("Unable to list volumes");
     });
   });
 
-  describe('fixPermissions', () => {
-    it('should fix write permissions on volume folder', async () => {
-      const outputs = [inspectOutput, ''];
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: outputs.shift() }));
+  describe("fixPermissions", () => {
+    it("should fix write permissions on volume folder", async () => {
+      const outputs = [inspectOutput, ""];
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: outputs.shift() }));
 
-      await expect(vm.fixPermissions({ name: 'test' })).resolves.toEqual(true);
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'inspect', 'test']);
-      expect(exec.exec).toHaveBeenCalledWith('chmod', ['-R', 'a+w', '/var/lib/docker/volumes/test/_data']);
+      await expect(vm.fixPermissions({ name: "test" })).resolves.toEqual(true);
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "inspect", "test"]);
+      expect(execMocks.exec).toHaveBeenCalledWith("chmod", ["-R", "a+w", "/var/lib/docker/volumes/test/_data"]);
     });
   });
 
-  describe('ls', () => {
-    it('should list files of a volume and path', async () => {
-      const outputs = [inspectOutput, 'dir', inspectOutput, 'a.txt\nb.txt'];
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: outputs.shift() }));
+  describe("ls", () => {
+    it("should list files of a volume and path", async () => {
+      const outputs = [inspectOutput, "dir", inspectOutput, "a.txt\nb.txt"];
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: outputs.shift() }));
 
-      await expect(vm.ls({ name: 'test' })).resolves.toEqual(['dir']);
-      await expect(vm.ls({ name: 'test', path: 'dir' })).resolves.toEqual(['a.txt', 'b.txt']);
+      await expect(vm.ls({ name: "test" })).resolves.toEqual(["dir"]);
+      await expect(vm.ls({ name: "test", path: "dir" })).resolves.toEqual(["a.txt", "b.txt"]);
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'inspect', 'test']);
-      expect(exec.exec).toHaveBeenCalledWith('ls', ['-1', '/var/lib/docker/volumes/test/_data']);
-      expect(exec.exec).toHaveBeenCalledWith('ls', ['-1', '/var/lib/docker/volumes/test/_data/dir']);
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "inspect", "test"]);
+      expect(execMocks.exec).toHaveBeenCalledWith("ls", ["-1", "/var/lib/docker/volumes/test/_data"]);
+      expect(execMocks.exec).toHaveBeenCalledWith("ls", ["-1", "/var/lib/docker/volumes/test/_data/dir"]);
     });
 
-    it('should throw an error if volume name is invalid', async () => {
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: '[]' }));
-      await expect(vm.ls({ name: 'notfound' })).rejects.toThrowError('Volume not found');
+    it("should throw an error if volume name is invalid", async () => {
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: "[]" }));
+      await expect(vm.ls({ name: "notfound" })).rejects.toThrowError("Volume not found");
     });
   });
 
-  describe('rm', () => {
-    it('should remove files of a volume by path', async () => {
-      const outputs = [inspectOutput, ''];
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: outputs.shift() }));
+  describe("rm", () => {
+    it("should remove files of a volume by path", async () => {
+      const outputs = [inspectOutput, ""];
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: outputs.shift() }));
 
-      await expect(vm.rm({ name: 'test', path: 'file.txt' })).resolves.toEqual(true);
+      await expect(vm.rm({ name: "test", path: "file.txt" })).resolves.toEqual(true);
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'inspect', 'test']);
-      expect(exec.exec).toHaveBeenCalledWith('rm', ['-r', '/var/lib/docker/volumes/test/_data/file.txt']);
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "inspect", "test"]);
+      expect(execMocks.exec).toHaveBeenCalledWith("rm", ["-r", "/var/lib/docker/volumes/test/_data/file.txt"]);
     });
 
-    it('should throw an error if volume name is invalid', async () => {
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: '[]' }));
-      await expect(vm.rm({ name: 'notfound', path: 'file.txt' })).rejects.toThrowError('Volume not found');
+    it("should throw an error if volume name is invalid", async () => {
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: "[]" }));
+      await expect(vm.rm({ name: "notfound", path: "file.txt" })).rejects.toThrowError("Volume not found");
     });
 
-    it('should throw an error if path is invalid', async () => {
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: inspectOutput }));
-      await expect(vm.rm({ name: 'nopath' })).rejects.toThrowError('Path not specified');
+    it("should throw an error if path is invalid", async () => {
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: inspectOutput }));
+      await expect(vm.rm({ name: "nopath" })).rejects.toThrowError("Path not specified");
       expect(execMocks.exec).not.toHaveBeenCalled();
     });
   });
 
-  describe('cat', () => {
-    it('should read the content of a file in a volume by path', async () => {
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: inspectOutput }));
-      fsMocks.readFile = jest.fn().mockImplementation(() => 'test file');
+  describe("cat", () => {
+    it("should read the content of a file in a volume by path", async () => {
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: inspectOutput }));
+      execMocks.readFile.mockImplementation(() => "test file");
 
-      await expect(vm.cat({ name: 'test', path: 'file.txt' })).resolves.toEqual('test file');
+      await expect(vm.cat({ name: "test", path: "file.txt" })).resolves.toEqual("test file");
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'inspect', 'test']);
-      expect(fs.readFile).toHaveBeenCalledWith('/var/lib/docker/volumes/test/_data/file.txt', 'utf8');
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "inspect", "test"]);
+      expect(execMocks.readFile).toHaveBeenCalledWith("/var/lib/docker/volumes/test/_data/file.txt", "utf8");
     });
 
-    it('should throw an error if volume name is invalid', async () => {
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: '[]' }));
-      await expect(vm.cat({ name: 'notfound', path: 'file.txt' })).rejects.toThrowError('Volume not found');
+    it("should throw an error if volume name is invalid", async () => {
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: "[]" }));
+      await expect(vm.cat({ name: "notfound", path: "file.txt" })).rejects.toThrowError("Volume not found");
     });
 
-    it('should throw an error if path is invalid', async () => {
-      execMocks.exec = jest.fn().mockImplementation(() => ({ ok: true, stdout: inspectOutput }));
-      await expect(vm.cat({ name: 'nopath' })).rejects.toThrowError('Path not specified');
+    it("should throw an error if path is invalid", async () => {
+      execMocks.exec.mockImplementation(() => ({ ok: true, stdout: inspectOutput }));
+      await expect(vm.cat({ name: "nopath" })).rejects.toThrowError("Path not specified");
       expect(execMocks.exec).not.toHaveBeenCalled();
     });
   });
 
-  describe('show', () => {
-    it('should show details of a volume', async () => {
+  describe("show", () => {
+    it("should show details of a volume", async () => {
       const execOutput = { ok: true, stdout: inspectOutput };
-      execMocks.exec = jest.fn().mockResolvedValue(execOutput);
+      execMocks.exec.mockResolvedValue(execOutput);
 
-      await expect(vm.show({ name: 'test' })).resolves.toEqual({
-        name: 'test',
-        createdAt: '2023-03-10T10:15:10Z',
+      await expect(vm.show({ name: "test" })).resolves.toEqual({
+        name: "test",
+        createdAt: "2023-03-10T10:15:10Z",
         labels: {
-          origin: 'test/container',
-          version: '534524',
+          origin: "test/container",
+          version: "534524",
         },
       });
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'inspect', 'test']);
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "inspect", "test"]);
     });
 
-    it('should throw an error if volume name is invalid', async () => {
-      execMocks.exec = jest.fn();
-      await expect(vm.show({ name: 'In$%valid' })).rejects.toThrowError('Invalid name');
-      expect(exec.exec).not.toHaveBeenCalled();
+    it("should throw an error if volume name is invalid", async () => {
+      await expect(vm.show({ name: "In$%valid" })).rejects.toThrowError("Invalid name");
+      expect(execMocks.exec).not.toHaveBeenCalled();
     });
 
-    it('should throw error if volume does not exist', async () => {
-      const output = { ok: true, stdout: '[]' };
-      execMocks.exec = jest.fn().mockResolvedValue(output);
+    it("should throw error if volume does not exist", async () => {
+      const output = { ok: true, stdout: "[]" };
+      execMocks.exec.mockResolvedValue(output);
 
-      await expect(vm.show({ name: 'invalid' })).rejects.toThrowError('Volume not found');
+      await expect(vm.show({ name: "invalid" })).rejects.toThrowError("Volume not found");
     });
   });
 
-  describe('add', () => {
-    it('should add a volume', async () => {
-      const execOutput = { ok: true, stdout: 'test' };
-      execMocks.exec = jest.fn().mockResolvedValue(execOutput);
+  describe("add", () => {
+    it("should add a volume", async () => {
+      execMocks.exec
+        .mockResolvedValueOnce({ ok: true, stdout: "test" })
+        .mockResolvedValueOnce({ ok: true, stdout: inspectOutput })
+        .mockResolvedValueOnce({ ok: true, stdout: "" });
 
-      await expect(vm.add({ name: 'test' })).resolves.toEqual(true);
+      await expect(vm.add({ name: "test" })).resolves.toEqual(true);
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'create', 'test']);
+      expect(execMocks.exec).toHaveBeenCalledWith("docker", ["volume", "create", "test"]);
     });
 
-    it('should throw error if volume name is invalid', async () => {
-      execMocks.exec = jest.fn();
-      await expect(vm.add({ name: 'In$%valid' })).rejects.toThrowError('Invalid name');
-      expect(exec.exec).not.toHaveBeenCalled();
+    it("should throw error if volume name is invalid", async () => {
+      await expect(vm.add({ name: "In$%valid" })).rejects.toThrowError("Invalid name");
+      expect(execMocks.exec).not.toHaveBeenCalled();
     });
 
-    it('should throw error if volume creation fails', async () => {
-      const output = { ok: false, stdout: '' };
-      execMocks.exec = jest.fn().mockResolvedValue(output);
+    it("should throw error if volume creation fails", async () => {
+      const output = { ok: false, stdout: "" };
+      execMocks.exec.mockResolvedValue(output);
 
-      await expect(vm.add({ name: 'failed' })).rejects.toThrowError('Unable to create volume');
+      await expect(vm.add({ name: "failed" })).rejects.toThrowError("Unable to create volume");
     });
   });
 
-  describe('remove', () => {
-    it('should add a volume', async () => {
-      const execOutput = { ok: true, stdout: '' };
-      execMocks.exec = jest.fn().mockResolvedValue(execOutput);
-
-      await expect(vm.remove({ name: 'test' })).resolves.toEqual(true);
+  describe("remove", () => {
+    it("should add a volume", async () => {
+      const execOutput = { ok: true, stdout: "" };
+      execMocks.exec.mockResolvedValue(execOutput);
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'rm', 'test']);
+      await expect(vm.remove({ name: "test" })).resolves.toEqual(true);
     });
 
-    it('should throw error if volume name is invalid', async () => {
-      execMocks.exec = jest.fn();
-      await expect(vm.remove({ name: 'In$%valid' })).rejects.toThrowError('Invalid name');
-      expect(exec.exec).not.toHaveBeenCalled();
+    it("should throw error if volume name is invalid", async () => {
+      await expect(vm.remove({ name: "In$%valid" })).rejects.toThrowError("Invalid name");
+      expect(execMocks.exec).not.toHaveBeenCalled();
     });
 
-    it('should throw error if volume removal fails', async () => {
-      const output = { ok: false, stdout: '' };
-      execMocks.exec = jest.fn().mockResolvedValue(output);
+    it("should throw error if volume removal fails", async () => {
+      const output = { ok: false, stdout: "" };
+      execMocks.exec.mockResolvedValue(output);
 
-      await expect(vm.remove({ name: 'failed' })).rejects.toThrowError('Unable to remove volume');
+      await expect(vm.remove({ name: "failed" })).rejects.toThrowError("Unable to remove volume");
     });
   });
 
-  describe('prune', () => {
-    it('should remove ununsed volumes', async () => {
-      const execOutput = { ok: true, stdout: '' };
-      execMocks.exec = jest.fn().mockResolvedValue(execOutput);
-
-      await expect(vm.prune()).resolves.toEqual('');
+  describe("prune", () => {
+    it("should remove ununsed volumes", async () => {
+      const execOutput = { ok: true, stdout: "" };
+      execMocks.exec.mockResolvedValue(execOutput);
 
-      expect(exec.exec).toHaveBeenCalledWith('docker', ['volume', 'prune']);
+      await expect(vm.prune()).resolves.toEqual("");
     });
   });
 });

package/src/index.ts

@@ -1,91 +1,104 @@
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
-import { exec } from '@cloud-cli/exec';
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { exec } from "@cloud-cli/exec";
+import { help } from "@cloud-cli/cli";
 
 const nameRe = /^[a-z][a-z0-9-]+$/;
 const isValidName = (name) => nameRe.test(name);
-const invalidNameError = new Error('Invalid name');
+const invalidNameError = new Error("Invalid name");
+const readOptions = (options: NameOption) => {
+  options.name ||= options._?.[0];
+  if (!isValidName(options.name)) {
+    throw invalidNameError;
+  }
+};
+
+interface Options {
+  _?: string[];
+}
 
-interface NameOption {
+interface NameOption extends Options {
   name: string;
 }
 
-interface NameAndPathOption {
+interface NameAndPathOption extends Options {
   name: string;
   path?: string;
 }
 
 async function list() {
-  const output = await exec('docker', ['volume', 'ls', '--format={{.Name}}']);
+  const output = await exec("docker", ["volume", "ls", "--format={{.Name}}"]);
 
   if (!output.ok) {
-    throw new Error('Unable to list volumes');
+    throw new Error("Unable to list volumes");
   }
 
-  return output.stdout.trim().split('\n');
+  return output.stdout.trim().split("\n");
 }
 
 async function getVolumeMountpoint(name): Promise<string> {
-  const output = await exec('docker', ['volume', 'inspect', name]);
+  const output = await exec("docker", ["volume", "inspect", name]);
   const volumes = JSON.parse(output.stdout);
 
   if (!volumes.length) {
-    throw new Error('Volume not found');
+    throw new Error("Volume not found");
   }
 
   return volumes[0].Mountpoint;
 }
 
 async function ls(options: NameAndPathOption) {
-  const { name, path = '' } = options;
+  readOptions(options);
+  const { name, path = "" } = options;
   const root = await getVolumeMountpoint(name);
-  const files = await exec('ls', ['-1', join(root, path)]);
+  const files = await exec("ls", ["-1", join(root, path)]);
 
-  return files.stdout.trim().split('\n').filter(Boolean);
+  return files.stdout.trim().split("\n").filter(Boolean);
 }
 
 async function fixPermissions(options: NameOption) {
+  readOptions(options);
   const { name } = options;
   const root = await getVolumeMountpoint(name);
-  const result = await exec('chmod', ['-R', 'a+w', root]);
+  const result = await exec("chmod", ["-R", "a+w", root]);
 
   return result.ok;
 }
 
 async function rm(options: NameAndPathOption) {
+  readOptions(options);
   const { name, path } = options;
 
   if (!path) {
-    throw new Error('Path not specified');
+    throw new Error("Path not specified");
   }
 
   const root = await getVolumeMountpoint(name);
-  const result = await exec('rm', ['-r', join(root, path)]);
+  const result = await exec("rm", ["-r", join(root, path)]);
 
   return result.ok;
 }
 
 async function cat(options: NameAndPathOption) {
+  readOptions(options);
   const { name, path } = options;
 
   if (!path) {
-    throw new Error('Path not specified');
+    throw new Error("Path not specified");
   }
 
   const root = await getVolumeMountpoint(name);
-  return await readFile(join(root, path), 'utf8');
+  return await readFile(join(root, path), "utf8");
 }
 
 async function show(options: NameOption) {
-  if (!isValidName(options.name)) {
-    throw invalidNameError;
-  }
+  readOptions(options);
 
-  const output = await exec('docker', ['volume', 'inspect', options.name]);
+  const output = await exec("docker", ["volume", "inspect", options.name]);
   const list = JSON.parse(output.stdout);
 
   if (!list.length) {
-    throw new Error('Volume not found');
+    throw new Error("Volume not found");
   }
 
   const { Name, Labels, CreatedAt } = list[0];
@@ -98,36 +111,57 @@ async function show(options: NameOption) {
 }
 
 async function add(options: NameOption) {
-  if (!isValidName(options.name)) {
-    throw invalidNameError;
-  }
-
-  const output = await exec('docker', ['volume', 'create', options.name]);
+  readOptions(options);
+  const output = await exec("docker", ["volume", "create", options.name]);
 
   if (output.ok) {
+    await fixPermissions(options);
     return true;
   }
 
-  throw new Error('Unable to create volume');
+  throw new Error("Unable to create volume");
 }
 
 async function remove(options: NameOption) {
-  if (!isValidName(options.name)) {
-    throw invalidNameError;
-  }
-
-  const output = await exec('docker', ['volume', 'rm', options.name]);
+  readOptions(options);
+  const output = await exec("docker", ["volume", "rm", options.name]);
 
   if (output.ok) {
     return true;
   }
 
-  throw new Error('Unable to remove volume');
+  throw new Error("Unable to remove volume");
 }
 
 async function prune() {
-  await exec('docker', ['volume', 'prune']);
-  return '';
+  await exec("docker", ["volume", "prune"]);
+  return "";
 }
 
-export default { add, remove, list, show, prune, ls, rm, cat, fixPermissions };
+export default {
+  add,
+  remove,
+  list,
+  show,
+  prune,
+  ls,
+  rm,
+  cat,
+  fixPermissions,
+  [help]: () => `Manage Docker volumes
+
+Available commands:
+  vm.add --name <name> - Create a new Docker volume (name must be lowercase alphanumeric with hyphens)
+  vm.remove --name <name> - Remove a Docker volume
+  vm.list - List all Docker volumes
+  vm.ls --name <name> [--path <path>] - List files in a volume
+  vm.cat --name <name> --path <path> - Read a file from a volume
+  vm.show --name <name> - Show volume details
+  vm.fixPermissions --name <name> - Fix permissions on a volume
+  vm.rm --name <name> --path <path> - Remove a file or directory from a volume
+  vm.prune - Remove all unused Docker volumes
+
+Options:
+  name - Volume name (lowercase alphanumeric with hyphens)
+  path - Path within the volume`,
+};