feat: make cli closer to npm (#413)

This commit makes some slight adjustments to the cli to make it closer to the npm cli. Mostly this means rewriting help messages, adding aliases and renaming arguments.
openupm · Nov 1, 2024 · f0b89c6 · f0b89c6
1 parent 4447a6c
commit f0b89c6
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 129 deletions.
diff --git a/src/cli/cmd-add.ts b/src/cli/cmd-add.ts
@@ -22,14 +22,9 @@ import { upstreamOpt } from "./opt-upstream";
 import { workDirOpt } from "./opt-wd";
 import { mustBePackageSpec } from "./validators";
 
-const packageSpecArg = new Argument(
-  "<pkg>",
-  "Reference to the package that should be added"
-).argParser(mustBePackageSpec);
-
-const otherPackageSpecsArg = new Argument(
-  "[otherPkgs...]",
-  "References to additional packages that should be added"
+const packageSpecsArg = new Argument(
+  "<package-spec...>",
+  "Specs of packages that should be added"
 ).argParser(eachValue(mustBePackageSpec));
 
 const addTestableOpt = new Option(
@@ -82,83 +77,91 @@ export function makeAddCmd(
   );
 
   return new Command("add")
-    .aliases(["install", "i"])
-    .addArgument(packageSpecArg)
-    .addArgument(otherPackageSpecsArg)
+    .aliases([
+      "ad",
+      "i",
+      "in",
+      "ins",
+      "inst",
+      "insta",
+      "instal",
+      "isnt",
+      "isnta",
+      "isntal",
+      "isntall",
+      "install",
+    ])
+    .addArgument(packageSpecsArg)
     .addOption(addTestableOpt)
     .addOption(forceOpt)
     .addOption(primaryRegistriesUrlOpt)
     .addOption(workDirOpt)
     .addOption(systemUserOpt)
     .addOption(upstreamOpt)
+    .summary("add a dependency to the project")
     .description(
-      `add package to manifest json
-openupm add <pkg> [otherPkgs...]
-openupm add <pkg>@<version> [otherPkgs...]`
+      `Add a dependency to the project as well as all indirect dependencies.
+openupm add com.some.package@latest
+openupm add com.some.package@1.2.3`
     )
     .action(
-      withErrorLogger(
-        log,
-        async function (packageSpec, otherPackageSpecs, options) {
-          const packageSpecs = [packageSpec].concat(otherPackageSpecs);
-
-          const projectDirectory = options.chdir;
-
-          const editorVersion = await determineEditorVersion(projectDirectory);
+      withErrorLogger(log, async function (packageSpecs, options) {
+        const projectDirectory = options.chdir;
 
-          if (typeof editorVersion === "string")
-            log.warn(
-              "editor.version",
-              `${editorVersion} is unknown, the editor version check is disabled`
-            );
-
-          const homePath = getHomePathFromEnv(process.env);
-          const upmConfigPath = getUserUpmConfigPathFor(
-            process.env,
-            homePath,
-            options.systemUser
-          );
+        const editorVersion = await determineEditorVersion(projectDirectory);
 
-          const sources = await Promise.all(
-            (options.registry ?? [openupmRegistryUrl]).map((it) =>
-              getRegistryAuth(upmConfigPath, it)
-            )
+        if (typeof editorVersion === "string")
+          log.warn(
+            "editor.version",
+            `${editorVersion} is unknown, the editor version check is disabled`
           );
 
-          if (options.upstream) sources.push(unityRegistry);
-
-          const addResults = await addDependencies(
-            projectDirectory,
-            typeof editorVersion === "string" ? null : editorVersion,
-            sources,
-            options.force,
-            options.test,
-            packageSpecs
-          );
-
-          recordEntries(addResults)
-            .map(([packageName, addResult]) => {
-              switch (addResult.type) {
-                case "added":
-                  return `added ${makePackageSpec(
-                    packageName,
-                    addResult.version
-                  )}`;
-                case "upgraded":
-                  return `modified ${packageName} ${addResult.fromVersion} => ${addResult.toVersion}`;
-                case "noChange":
-                  return `existed ${makePackageSpec(
-                    packageName,
-                    addResult.version
-                  )}`;
-              }
-            })
-            .forEach((message) => {
-              log.notice("", message);
-            });
-
-          log.notice("", "please open Unity project to apply changes.");
-        }
-      )
+        const homePath = getHomePathFromEnv(process.env);
+        const upmConfigPath = getUserUpmConfigPathFor(
+          process.env,
+          homePath,
+          options.systemUser
+        );
+
+        const sources = await Promise.all(
+          (options.registry ?? [openupmRegistryUrl]).map((it) =>
+            getRegistryAuth(upmConfigPath, it)
+          )
+        );
+
+        if (options.upstream) sources.push(unityRegistry);
+
+        const addResults = await addDependencies(
+          projectDirectory,
+          typeof editorVersion === "string" ? null : editorVersion,
+          sources,
+          options.force,
+          options.test,
+          packageSpecs
+        );
+
+        recordEntries(addResults)
+          .map(([packageName, addResult]) => {
+            switch (addResult.type) {
+              case "added":
+                return `added ${makePackageSpec(
+                  packageName,
+                  addResult.version
+                )}`;
+              case "upgraded":
+                return `modified ${packageName} ${addResult.fromVersion} => ${addResult.toVersion}`;
+              case "noChange":
+                return `existed ${makePackageSpec(
+                  packageName,
+                  addResult.version
+                )}`;
+            }
+          })
+          .forEach((message) => {
+            log.notice("", message);
+          });
+
+        log.notice("", "please open Unity project to apply changes.");
+      })
     );
 }
diff --git a/src/cli/cmd-deps.ts b/src/cli/cmd-deps.ts
@@ -27,8 +27,8 @@ import { ResultCodes } from "./result-codes";
 import { mustBePackageSpec } from "./validators";
 
 const packageSpecArg = new Argument(
-  "<pkg>",
-  "Reference to a package"
+  "<package-spec>",
+  "Spec of package for which to view dependencies"
 ).argParser(mustBePackageSpec);
 
 const deepOpt = new Option(

diff --git a/src/cli/cmd-login.ts b/src/cli/cmd-login.ts
@@ -75,7 +75,11 @@ export function makeLoginCmd(
     .addOption(alwaysAuthOpt)
     .addOption(registryOpt)
     .addOption(systemUserOpt)
-    .description("authenticate with a scoped registry")
+    .summary("authenticate with a 3rd party registry")
+    .description(
+      `Authenticate with a specified 3rd party registry and stores credentials in the users \`.npmrc\`.
+openupm login -r https://packages.my-registry.com -u user123 -p ****** -e user123@mail.com`
+    )
     .action(
       withErrorLogger(log, async function (options) {
         const homePath = getHomePathFromEnv(process.env);

diff --git a/src/cli/cmd-remove.ts b/src/cli/cmd-remove.ts
@@ -11,14 +11,9 @@ import { workDirOpt } from "./opt-wd";
 import { ResultCodes } from "./result-codes";
 import { mustBeDomainName } from "./validators";
 
-const packageNameArg = new Argument(
-  "<pkg>",
-  "Name of the package to remove"
-).argParser(mustBeDomainName);
-
-const otherPackageNamesArg = new Argument(
-  "[otherPkgs...]",
-  "Names of additional packages to remove"
+const packageNamesArg = new Argument(
+  "<pkg...>",
+  "Names of the packages to remove"
 ).argParser(eachValue(mustBeDomainName));
 
 /**
@@ -43,42 +38,38 @@ export function makeRemoveCmd(
   );
 
   return new Command("remove")
-    .aliases(["rm", "uninstall"])
-    .addArgument(packageNameArg)
-    .addArgument(otherPackageNamesArg)
+    .aliases(["rm", "r", "un", "unlink", "uninstall"])
+    .addArgument(packageNamesArg)
     .addOption(workDirOpt)
-    .description("remove package from manifest json")
+    .summary("remove dependency from project")
+    .description(
+      `Remove one or more dependencies from a project.
+openupm remove com.my.package`
+    )
     .action(
-      withErrorLogger(
-        log,
-        async function (packageName, otherPackageNames, options) {
-          const packageNames = [packageName, ...otherPackageNames];
-
-          const projectDir = options.chdir;
+      withErrorLogger(log, async function (packageNames, options) {
+        const projectDir = options.chdir;
 
-          const removeResult = await removeDependencies(
-            projectDir,
-            packageNames
-          ).promise;
-          if (removeResult.isErr()) {
-            logError(log, removeResult.error);
-            return process.exit(ResultCodes.Error);
-          }
-          const removedPackages = removeResult.value;
+        const removeResult = await removeDependencies(projectDir, packageNames)
+          .promise;
+        if (removeResult.isErr()) {
+          logError(log, removeResult.error);
+          return process.exit(ResultCodes.Error);
+        }
+        const removedPackages = removeResult.value;
 
-          removedPackages.forEach((removedPackage) => {
-            log.notice(
-              "",
-              `Removed "${makePackageSpec(
-                removedPackage.name,
-                removedPackage.version
-              )}".`
-            );
-          });
+        removedPackages.forEach((removedPackage) => {
+          log.notice(
+            "",
+            `Removed "${makePackageSpec(
+              removedPackage.name,
+              removedPackage.version
+            )}".`
+          );
+        });
 
-          // print manifest notice
-          log.notice("", "please open Unity project to apply changes");
-        }
-      )
+        // print manifest notice
+        log.notice("", "please open Unity project to apply changes");
+      })
     );
 }
diff --git a/src/cli/cmd-search.ts b/src/cli/cmd-search.ts
@@ -47,13 +47,15 @@ export function makeSearchCmd(
   );
 
   return new Command("search")
-    .argument("<keyword>", "The keyword to search")
+    .argument("<search term>", "The term to search for")
     .addOption(primaryRegistryUrlOpt)
     .addOption(systemUserOpt)
     .aliases(["s", "se", "find"])
-    .description("Search package by keyword")
+    .summary("search packages matching a term")
+    .description(`Search all packages matching a given search term.
+openupm search math`)
     .action(
-      withErrorLogger(log, async function (keyword, options) {
+      withErrorLogger(log, async function (searchTerm, options) {
         const homePath = getHomePathFromEnv(process.env);
         const upmConfigPath = getUserUpmConfigPathFor(
           process.env,
@@ -67,16 +69,20 @@ export function makeSearchCmd(
         );
 
         let usedEndpoint = "npmsearch";
-        const results = await searchPackages(primaryRegistry, keyword, () => {
-          usedEndpoint = "endpoint.all";
-          log.warn(
-            "",
-            "fast search endpoint is not available, using old search."
-          );
-        });
+        const results = await searchPackages(
+          primaryRegistry,
+          searchTerm,
+          () => {
+            usedEndpoint = "endpoint.all";
+            log.warn(
+              "",
+              "fast search endpoint is not available, using old search."
+            );
+          }
+        );
 
         if (results.length === 0) {
-          log.notice("", `No matches found for "${keyword}"`);
+          log.notice("", `No matches found for "${searchTerm}"`);
           return process.exit(ResultCodes.Ok);
         }
 

diff --git a/src/cli/cmd-view.ts b/src/cli/cmd-view.ts
@@ -41,12 +41,16 @@ export function makeViewCmd(
   );
 
   return new Command("view")
-    .argument("<pkg>", "Reference to a package", mustBePackageSpec)
+    .argument("<package-spec>", "Spec of a package", mustBePackageSpec)
     .addOption(primaryRegistryUrlOpt)
     .addOption(systemUserOpt)
     .addOption(upstreamOpt)
     .aliases(["v", "info", "show"])
-    .description("view package information")
+    .summary("view package information")
+    .description(
+      `Print information about a remote package.
+openupm view com.some.package`
+    )
     .action(
       withErrorLogger(log, async function (packageSpec, options) {
         const homePath = getHomePathFromEnv(process.env);