feat: add new sf crud-mdapi read command (#117)

The new `sf crud-mdapi read` command replaces `sf force source read` which is now deprecated and will be removed in the next major release (`v2`).

- **new flags**: `--output-dir` and `--manifest`
- **renamed flag**: `--sourcepath` (`-p`) is now `--source-dir` (`-d`)
- **changed flag**: `--metadata` can now be specified multiple times instead of only once as comma-separated string
- the global sf flag `--flags-dir` is now supported
- Metadata like `CustomObjectTranslation` is now **decomposed** into multiple files (e.g. `.objectTranslation-meta.xml`, `.fieldTranslation-meta.xml`)

Please see the [Migration Guide](https://github.com/amtrack/sfdx-plugin-source-read/wiki/Migration#sf-crud-mdapi-read).

Author: amtrack

.github/workflows/default.yml

@@ -22,17 +22,12 @@ jobs:
           npm install --global @salesforce/cli
       - name: Run tests
         run: npm run test
-      - name: Run E2E tests
+      - name: Run E2E tests in Developer Edition
         env:
-          SFDX_AUTH_URL_DEVHUB: ${{ secrets.SFDX_AUTH_URL_DEVHUB }}
+          SFDX_AUTH_URL_DEVED: ${{ secrets.SFDX_AUTH_URL_DEVED }}
         run: |
-          echo "${SFDX_AUTH_URL_DEVHUB}" | sf org login sfdx-url --set-default-dev-hub --alias devhub --sfdx-url-stdin
-          sf org create scratch -f config/project-scratch-def.json --set-default
+          echo "${SFDX_AUTH_URL_DEVED}" | sf org login sfdx-url --set-default --alias deved --sfdx-url-stdin
           npm run test:e2e
-      - name: Delete scratch org
-        if: always()
-        run: |
-          sf org delete scratch --no-prompt
       - name: Release package
         run: npx semantic-release
         env:

README.md

@@ -4,7 +4,14 @@
 
 For certain Metadata Types there is a different behaviour of the [file-based](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_retrieve.htm) vs. [CRUD-based](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_readMetadata.htm) Metadata API.
 
-This plugin provides a `sf force source read` command to read Metadata using the "CRUD-based" Metadata API similar to `sf force source retrieve` (which uses the "file-based" Metadata API).
+And additionally the file-based Metadata API even behaves differently for source-tracked vs. non-source-tracked orgs.
+
+> [!IMPORTANT]
+> The CRUD-based Metadata API can be of great help when working with non-source-tracked orgs.
+>
+> Read more about about this in my [mdapi-issues/retrieve-behavior-scratch-org](https://github.com/mdapi-issues/retrieve-behavior-scratch-org) repository.
+
+This plugin provides a `sf crud-mdapi read` (formerly `sf force source read`) command to read Metadata using the "CRUD-based" Metadata API similar to `sf project retrieve start` (which uses the "file-based" Metadata API).
 
 > [!NOTE]
 > This plugin simply returns the unfiltered response from the CRUD-based Metadata API.
@@ -20,11 +27,11 @@ sf plugins install sfdx-plugin-source-read
 ## Usage
 
 ```console
-sf force source read -m "Profile:Admin"
-sf force source read -p force-app/main/default/profiles/Admin.profile-meta.xml
-sf force source read -m "RecordType:Account.Business"
-sf force source read -p force-app/main/default/objects/Account/recordTypes/Business.recordType-meta.xml
-sf force source read -m "CustomObjectTranslation:Task-de"
+sf crud-mdapi read --metadata "Profile:Admin" --metadata "Profile:Standard"
+sf crud-mdapi read --source-dir force-app/main/default/profiles/Admin.profile-meta.xml
+sf crud-mdapi read --metadata "RecordType:Account.Business"
+sf crud-mdapi read --source-dir force-app/main/default/objects/Account/recordTypes/Business.recordType-meta.xml
+sf crud-mdapi read --metadata "CustomObjectTranslation:Task-de"
 ```
 
 ## Example

bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

bin/dev.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
+// eslint-disable-next-line node/shebang
+async function main() {
+  const { execute } = await import("@oclif/core");
+  await execute({ development: true, dir: import.meta.url });
+}
+
+await main();

bin/run.cmd

@@ -3,5 +3,9 @@
   "edition": "Developer",
   "language": "en_US",
   "features": [],
-  "settings": {}
+  "settings": {
+    "languageSettings": {
+      "enableTranslationWorkbench": true
+    }
+  }
 }