Migrate to npx (#161)

See ADR 4 for details.

README.md

@@ -44,29 +44,22 @@ When(a.ConfigMap)
 
 - [Node.js](https://nodejs.org/en/) v18.0.0+.
 
-  > _Recommend installing with [NVM](https://github.com/nvm-sh/nvm) or [NVM for Windows](https://github.com/coreybutler/nvm-windows) to avoid permission issues when installing the Pepr CLI globally._
-
 - Recommended (optional) tools:
   - [Visual Studio Code](https://code.visualstudio.com/) for inline debugging and [Pepr Capabilities](#capability) creation.
-  - A Kubernetes cluster for `pepr dev`. Pepr modules include `npm run k3d-setup` if you want to test locally with [K3d](https://k3d.io/) and [Docker](https://www.docker.com/).
+  - A Kubernetes cluster for `npx pepr dev`. Pepr modules include `npm run k3d-setup` if you want to test locally with [K3d](https://k3d.io/) and [Docker](https://www.docker.com/).
 
 ## Wow too many words! tl;dr;
 
 ```bash
-# Install Pepr globally. If this command requires sudo, see the Prerequisites section to install Node.js with NVM or NVM for Windows.
-npm i -g pepr
-
-# Initialize a new Pepr Module
-pepr init
-
-# Follow the prompts...
+# Initialize a new Pepr Module, you can also use `npx pepr@latest init` to make sure you have the latest version
+npx pepr init
 
 # If you already have a Kind or K3d cluster you want to use, skip this step
 npm run k3d-setup
 
 # Start playing with Pepr now
-# If using another local K8s distro instead of k3d, run `pepr dev --host host.docker.internal`
-pepr dev
+# If using another local K8s distro instead of k3d, run `npx pepr dev --host host.docker.internal`
+npx pepr dev
 kubectl apply -f capabilities/hello-pepr.samples.yaml
 
 # Be amazed and ⭐️ this repo

adr/0004-use-npx-instead-of-global-cli-install.md

@@ -0,0 +1,48 @@
+# 4. Use NPX instead of global CLI install
+
+Date: 2023-06-18
+
+## Status
+
+Accepted
+
+## Context
+
+Pepr requires users to install the CLI globally via npm, and manage the SDK version separately through `pepr update`. This approach has led to issues including permission problems during global installation and inconsistencies between CLI and SDK versions.
+
+While `pepr update` does help with SDK version consistency, the version consistency between the CLI and SDK is not guaranteed. This is because the CLI is installed globally, while the SDK is installed locally. This can lead to issues where the CLI is not compatible with the SDK, or vice versa.
+
+Other tools, like Playwright, utilize `npm init <package-name>` and `npx <package-name> <command>` to ensure consistency and avoid global installation issues. However, further investigation revealed that `npm init` approach is not ideal for Pepr due to the requirement for a separate published package and lack of clarity for new users over simply using `npx`.
+
+## Decision
+
+We will migrate from requiring a global Pepr installation to using `npx` for executing the Pepr CLI. This will ensure that users always execute the correct version of the CLI that is compatible with their local SDK.
+
+The proposed commands for using Pepr will be:
+
+```bash
+npx pepr@latest init # @latest is optional
+npx pepr build
+npx pepr dev
+npx pepr ... # Other commands
+```
+
+This approach has the following benefits:
+
+1. **Version Consistency**: The CLI and SDK versions are guaranteed to be consistent since both are executed from the local `node_modules`.
+
+1. **Permissions**: By avoiding global installations, users won't face permission issues which are common especially on UNIX based systems.
+
+1. **Simplicity**: Still only one command pattern is required to use Pepr, and users don't need to worry about updating the CLI and SDK separately.
+
+However, the new approach has a slight disadvantage that users would have to prefix `npx` before every Pepr command, which might be considered less clean compared to the global installation approach.
+
+## Consequences
+
+1. **Update Documentation**: All documentation and references to Pepr commands will need to be updated to reflect the use of `npx`.
+
+1. **User Adaptation**: Users might need some time to adapt to the new syntax, especially prefixing commands with `npx`.
+
+## Date
+
+18th June 2023

hack/e2e.test.mjs

@@ -42,7 +42,8 @@ test.before(async t => {
 
 test.serial("E2E: `pepr init`", t => {
   try {
-    execSync("TEST_MODE=true pepr init", { stdio: "inherit" });
+    const peprAlias = "file:pepr-0.0.0-development.tgz"
+    execSync(`TEST_MODE=true npx --yes ${peprAlias} init`, { stdio: "inherit" });
     t.pass();
   } catch (e) {
     t.fail(e.message);
@@ -51,7 +52,7 @@ test.serial("E2E: `pepr init`", t => {
 
 test.serial("E2E: `pepr format`", t => {
   try {
-    execSync("pepr format", { cwd: testDir, stdio: "inherit" });
+    execSync("npx pepr format", { cwd: testDir, stdio: "inherit" });
     t.pass();
   } catch (e) {
     t.fail(e.message);
@@ -60,7 +61,7 @@ test.serial("E2E: `pepr format`", t => {
 
 test.serial("E2E: `pepr build`", async t => {
   try {
-    execSync("pepr build", { cwd: testDir, stdio: "inherit" });
+    execSync("npx pepr build", { cwd: testDir, stdio: "inherit" });
     // check if the file exists
     await fs.access(resolve(testDir, "dist", "zarf.yaml"));
     await fs.access(resolve(testDir, "dist", "pepr-module-static-test.yaml"));
@@ -74,7 +75,7 @@ test.serial("E2E: `pepr build`", async t => {
 test.serial("E2E: `pepr deploy`", async t => {
   try {
     // Deploy the module
-    execSync("pepr deploy -i pepr:dev --confirm", { cwd: testDir, stdio: "inherit" });
+    execSync("npx pepr deploy -i pepr:dev --confirm", { cwd: testDir, stdio: "inherit" });
 
     // Wait for the deployment to be ready
     await waitForDeploymentReady("pepr-system", "pepr-static-test");
@@ -214,7 +215,7 @@ async function testAPIKey() {
   process.env.NODE_TLS_REJECT_UNAUTHORIZED = "1";
 }
 function peprDev(resolve, reject) {
-  const cmd = spawn("pepr", ["dev", "--confirm"], { cwd: testDir });
+  const cmd = spawn("npx", ["pepr", "dev", "--confirm"], { cwd: testDir });
 
   cmd.stdout.on("data", data => {
     // Convert buffer to string

package.json

@@ -19,7 +19,7 @@
     "test:unit": "npm run build && tsc -p tsconfig.tests.json && ava dist/**/*.test.js",
     "test:e2e": "npm run test:e2e:k3d && npm run test:e2e:build && npm run test:e2e:image && npm run test:e2e:run",
     "test:e2e:k3d": "k3d cluster delete pepr-dev && k3d cluster create pepr-dev --k3s-arg '--debug@server:0'",
-    "test:e2e:build": "npm run build && npm pack && npm uninstall pepr -g && npm install -g pepr-0.0.0-development.tgz && pepr",
+    "test:e2e:build": "npm run build && npm pack",
     "test:e2e:image": "docker buildx build --tag pepr:dev . && k3d image import pepr:dev -c pepr-dev",
     "test:e2e:run": "ava hack/e2e.test.mjs --sequential --timeout=2m",
     "format:check": "eslint src && prettier src --check",

src/cli/update.ts

@@ -48,11 +48,6 @@ export default function (program: RootCmd) {
           stdio: "inherit",
         });
 
-        // Update Pepr globally
-        execSync("npm install -g pepr@latest", {
-          stdio: "inherit",
-        });
-
         console.log(`Module updated!`);
       } catch (e) {
         Log.debug(e);