sfdx-predeploy-hook-org-env 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# sfdx-predeploy-hook-org-env
+
+> sfdx predeploy hook to export target org details as environment variables
+
+This is useful for [Metadata String Replacements](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_string_replace.htm) before pushing/deploying to an org (especially Scratch Orgs).
+
+Currently supported environment variables:
+
+| Environment Variable               | Description                             | Example              |
+| ---------------------------------- | --------------------------------------- | -------------------- |
+| `SFDX_TARGET_ORG_USERNAME`         | The username of the target org user     | john.doe@example.com |
+| `SFDX_TARGET_ORG_ID`               | The id of the target org                | 00D7g0000006RKmEAM   |
+| `SFDX_TARGET_ORG_USER_EMAIL`       | The email of the target org user        | john.doe@gmail.com   |
+| `SFDX_TARGET_ORG_USER_FIRSTNAME`   | The first name of the target org user   | John                 |
+| `SFDX_TARGET_ORG_USER_LASTNAME`    | The last name of the target org user    | Doe                  |
+| `SFDX_TARGET_ORG_USER_DISPLAYNAME` | The display name of the target org user | John Doe             |
+| `SFDX_TARGET_ORG_USER_ID`          | The id of the target org user           | 0058F000002RfcKQAS   |
+
+> **Note**
+>
+> This is a minimalistic sfdx plugin.
+>
+> Ideally sfdx supports dynamic Metadata String Replacements with custom Bash/Node.js scripts in the future.
+
+## Installation
+
+```console
+sfdx plugins install sfdx-predeploy-hook-org-env
+```
+
+## Usage
+
+Make sure your `sfdx-project.json` contains some `replacements`.
+
+Example:
+
+```json
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "sourceApiVersion": "57.0",
+  "replacements": [
+    {
+      "filename": "*.portal-meta.xml",
+      "stringToReplace": "john.doe@example.com",
+      "replaceWithEnv": "SFDX_TARGET_ORG_USERNAME"
+    },
+    {
+      "filename": "*.portal-meta.xml",
+      "stringToReplace": "john.doe@gmail.com",
+      "replaceWithEnv": "SFDX_TARGET_ORG_USER_EMAIL"
+    }
+  ]
+}
+```
+
+To preview the environment variables,
+set the environment variable `DEBUG=sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy`
+and perform a validation deployment to the target org.
+
+**Example**
+
+MacOS/Linux:
+
+```console
+$ DEBUG=sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy sfdx force source deploy --checkonly -u mytargetorg -p force-app
+```
+
+Windows PowerShell:
+
+```powershell
+$env:DEBUG=sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy
+sfdx force source deploy --checkonly -u mytargetorg -p force-app
+```
+
+This will output something like:
+
+```
+...
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy Setting environment variables for target org +2s
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_ID="00D7g0000006RKmEAM"
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USERNAME="john.doe@example.com"
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_ID="0058F000002RfcKQAS"
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_EMAIL="john.doe@gmail.com"
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_FIRSTNAME="John"
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_LASTNAME="Doe"
+sfdx:sfdx-predeploy-hook-org-env:hooks:predeploy SFDX_TARGET_ORG_USER_DISPLAYNAME="John Doe" +0ms
+...
+```

package/oclif.manifest.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.0.0-development",
+  "commands": {}
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "sfdx-predeploy-hook-org-env",
+  "version": "1.0.0",
+  "description": "sfdx predeploy hook to export target org details as environment variables",
+  "license": "MIT",
+  "files": [
+    "/src",
+    "/oclif.manifest.json"
+  ],
+  "oclif": {
+    "bin": "sfdx",
+    "hooks": {
+      "predeploy": "./src/hook.mjs"
+    }
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@oclif/core": "2.x",
+    "@salesforce/core": "3.x"
+  },
+  "devDependencies": {
+    "@oclif/core": "2.6.2",
+    "@salesforce/core": "3.34.6"
+  },
+  "scripts": {
+    "test:e2e": "bash scripts/test-e2e.sh"
+  },
+  "keywords": [
+    "sfdx",
+    "sfdx-plugin",
+    "sfdx-hook",
+    "hook"
+  ]
+}

package/src/hook.mjs

@@ -0,0 +1,24 @@
+import { getTargetOrgFromHook } from "./target-org.mjs";
+
+export async function hook(options) {
+  const org = await getTargetOrgFromHook(options);
+  const identity = await org.getConnection().identity();
+  const env = {
+    SFDX_TARGET_ORG_ID: identity.organization_id,
+    SFDX_TARGET_ORG_USERNAME: identity.username,
+    SFDX_TARGET_ORG_USER_ID: identity.user_id,
+    SFDX_TARGET_ORG_USER_EMAIL: identity.email,
+    SFDX_TARGET_ORG_USER_FIRSTNAME: identity.first_name,
+    SFDX_TARGET_ORG_USER_LASTNAME: identity.last_name,
+    SFDX_TARGET_ORG_USER_DISPLAYNAME: identity.display_name,
+  };
+  this.debug("Setting environment variables for target org");
+  this.debug(
+    Object.entries(env)
+      .map(([k, v]) => `${k}="${v}"`)
+      .join("\n")
+  );
+  for (const [k, v] of Object.entries(env)) {
+    process.env[k] = v;
+  }
+}

package/src/target-org.mjs

@@ -0,0 +1,14 @@
+import { Parser } from "@oclif/core";
+import { Org } from "@salesforce/core";
+
+export async function getTargetOrgFromHook(hookOptions) {
+  // dynamically parse the flags for the source deploy/push/delete commands
+  const { flags } = await Parser.parse(hookOptions.argv, hookOptions.Command);
+  const aliasOrUsername = flags["target-org"] ?? flags.targetusername;
+  const org = aliasOrUsername
+    ? // use the command line flag if given
+      await Org.create({ aliasOrUsername })
+    : // fallback to SFDX_DEFAULTUSERNAME environment variable or default org
+      await Org.create();
+  return org;
+}