@marsson/ciutils 0.1.0 → 0.2.1

package/README.md

@@ -1,260 +1,142 @@
-# ciutils
+# SF-CIUtils: Salesforce CI/CD Utilities 🚀
 
-[![NPM](https://img.shields.io/npm/v/ciutils.svg?label=ciutils)](https://www.npmjs.com/package/ciutils) [![Downloads/week](https://img.shields.io/npm/dw/ciutils.svg)](https://npmjs.org/package/ciutils) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/salesforcecli/ciutils/main/LICENSE.txt)
+[![NPM](https://img.shields.io/npm/v/@marsson/ciutils.svg?label=@marsson/ciutils)](https://www.npmjs.com/package/@marsson/ciutils) 
+[![Downloads/week](https://img.shields.io/npm/dw/@marsson/ciutils.svg)](https://npmjs.org/package/@marsson/ciutils) 
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/salesforcecli/ciutils/main/LICENSE.txt)
+[![codecov](https://codecov.io/gh/marsson/sf-ciutils/branch/main/graph/badge.svg)](https://codecov.io/gh/marsson/sf-ciutils)
 
-## Using the template
+## 🌟 What is SF-CIUtils?
 
-This repository provides a template for creating a plugin for the Salesforce CLI. To convert this template to a working plugin:
+SF-CIUtils is a powerful toolkit for Salesforce developers who want to supercharge their CI/CD workflows! This plugin for the Salesforce CLI provides essential utilities that make continuous integration and deployment with Salesforce a breeze.
 
-1. Please get in touch with the Platform CLI team. We want to help you develop your plugin.
-2. Generate your plugin:
+Think of it as your Swiss Army knife for Salesforce CI/CD operations - whether you're validating repository metadata, monitoring deployments, managing file uploads, or handling user permissions, SF-CIUtils has got you covered!
 
-   ```
-   sf plugins install dev
-   sf dev generate plugin
-
-   git init -b main
-   git add . && git commit -m "chore: initial commit"
-   ```
-
-3. Create your plugin's repo in the salesforcecli github org
-4. When you're ready, replace the contents of this README with the information you want.
-
-## Learn about `sf` plugins
-
-Salesforce CLI plugins are based on the [oclif plugin framework](<(https://oclif.io/docs/introduction.html)>). Read the [plugin developer guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_plugins.meta/sfdx_cli_plugins/cli_plugins_architecture_sf_cli.htm) to learn about Salesforce CLI plugin development.
-
-This repository contains a lot of additional scripts and tools to help with general Salesforce node development and enforce coding standards. You should familiarize yourself with some of the [node developer packages](#tooling) used by Salesforce.
-
-Additionally, there are some additional tests that the Salesforce CLI will enforce if this plugin is ever bundled with the CLI. These test are included by default under the `posttest` script and it is required to keep these tests active in your plugin if you plan to have it bundled.
-
-### Tooling
-
-- [@salesforce/core](https://github.com/forcedotcom/sfdx-core)
-- [@salesforce/kit](https://github.com/forcedotcom/kit)
-- [@salesforce/sf-plugins-core](https://github.com/salesforcecli/sf-plugins-core)
-- [@salesforce/ts-types](https://github.com/forcedotcom/ts-types)
-- [@salesforce/ts-sinon](https://github.com/forcedotcom/ts-sinon)
-- [@salesforce/dev-config](https://github.com/forcedotcom/dev-config)
-- [@salesforce/dev-scripts](https://github.com/forcedotcom/dev-scripts)
-
-### Hooks
-
-For cross clouds commands, e.g. `sf env list`, we utilize [oclif hooks](https://oclif.io/docs/hooks) to get the relevant information from installed plugins.
-
-This plugin includes sample hooks in the [src/hooks directory](src/hooks). You'll just need to add the appropriate logic. You can also delete any of the hooks if they aren't required for your plugin.
-
-# Everything past here is only a suggestion as to what should be in your specific plugin's description
+## ✨ Features
 
-This plugin is bundled with the [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli). For more information on the CLI, read the [getting started guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm).
+- **Validate Repository Metadata**: Compare your local metadata with what's in your org to catch metadata drift
+- **Report on Deployments**: Get detailed, real-time information about your deployments
+- **Create Files**: Upload files to Salesforce with ease
+- **Remove Assignments**: Efficiently manage permission sets, permission set groups, and group assignments
 
-We always recommend using the latest version of these commands bundled with the CLI, however, you can install a specific version or tag if needed.
-
-## Install
+## 🚀 Installation
 
 ```bash
-sf plugins install ciutils@x.y.z
+sf plugins install @marsson/ciutils
 ```
 
-## Issues
-
-Please report any issues at https://github.com/forcedotcom/cli/issues
-
-## Contributing
-
-1. Please read our [Code of Conduct](CODE_OF_CONDUCT.md)
-2. Create a new issue before starting your project so that we can keep track of
-   what you are trying to add/fix. That way, we can also offer suggestions or
-   let you know if there is already an effort in progress.
-3. Fork this repository.
-4. [Build the plugin locally](#build)
-5. Create a _topic_ branch in your fork. Note, this step is recommended but technically not required if contributing using a fork.
-6. Edit the code in your fork.
-7. Write appropriate tests for your changes. Try to achieve at least 95% code coverage on any new code. No pull request will be accepted without unit tests.
-8. Sign CLA (see [CLA](#cla) below).
-9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.
+Or install a specific version:
 
-### CLA
+```bash
+sf plugins install @marsson/ciutils@x.y.z
+```
 
-External contributors will be required to sign a Contributor's License
-Agreement. You can do so by going to https://cla.salesforce.com/sign-cla.
+## 🔧 Commands
 
-### Build
+### `sf validate repository metadata`
 
-To build the plugin locally, make sure to have yarn installed and run the following commands:
+This command helps you validate your local metadata against what's in your Salesforce org. It's like having a detective that spots differences between your local files and what's actually deployed!
 
 ```bash
-# Clone the repository
-git clone git@github.com:salesforcecli/ciutils
-
-# Install the dependencies and compile
-yarn && yarn build
+sf validate repository metadata --folder path/to/metadata --target-org your-org
 ```
 
-To use your plugin, run using the local `./bin/dev` or `./bin/dev.cmd` file.
+**Example**: Check if your local Apex classes match what's in your production org:
 
 ```bash
-# Run using local run file.
-./bin/dev hello world
+sf validate repository metadata --folder force-app/main/default/classes --target-org production
 ```
 
-There should be no differences when running via the Salesforce CLI or using the local run file. However, it can be useful to link the plugin to do some additional testing or run your commands from anywhere on your machine.
+### `sf reporton deployment`
+
+Keep an eye on your deployments with this command. It's like having a deployment dashboard right in your terminal!
 
 ```bash
-# Link your plugin to the sf cli
-sf plugins link .
-# To verify
-sf plugins
+sf reporton deployment --deploymentid 0AfXXXXXXXXXXXXXXX --target-org your-org
 ```
 
-## Commands
-
-<!-- commands -->
-* [`sf create file`](#sf-create-file)
-* [`sf remove assignments`](#sf-remove-assignments)
-* [`sf reporton deployment`](#sf-reporton-deployment)
-* [`sf validate repository metadata`](#sf-validate-repository-metadata)
-
-## `sf create file`
-
-Upload a local file to an org.
+**Example**: Monitor a deployment and wait for it to complete:
 
+```bash
+sf reporton deployment --deploymentid 0AfXXXXXXXXXXXXXXX --target-org production --awaitcompletion
 ```
-USAGE
-  $ sf create file -o <value> -f <value> [--json] [--flags-dir <value>] [--api-version <value>] [-t <value>] [-i
-    <value>] [-c <value>]
-
-FLAGS
-  -c, --created-date=<value>  Datetime value in ISO 8601 format (e.g., 2024-08-09T15:30:00Z).
-  -f, --file=<value>          (required) Path of file to upload.
-  -i, --parent-id=<value>     ID of the record to attach the file to.
-  -o, --target-org=<value>    (required) Username or alias of the target org. Not required if the `target-org`
-                              configuration variable is already set.
-  -t, --title=<value>         New title given to the file (ContentDocument) after it's uploaded.
-      --api-version=<value>   Override the api version used for api requests made by this command
 
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
+### `sf create file`
 
-DESCRIPTION
-  Upload a local file to an org.
+Upload files to your Salesforce org with this handy command. Perfect for adding documents, images, or any other files to your org!
 
-  This command always creates a new file in the org; you can't update an existing file. After a successful upload, the
-  command displays the ID of the new ContentDocument record which represents the uploaded file.
-
-  By default, the uploaded file isn't attached to a record; in the Salesforce UI the file shows up in the Files tab. You
-  can optionally attach the file to an existing record, such as an account, as long as you know its record ID.
-
-  You can also give the file a new name after it's been uploaded; by default its name in the org is the same as the
-  local file name.
-
-EXAMPLES
-  Upload the local file "resources/astro.png" to your default org:
-
-    $ sf create file --file resources/astro.png
-
-  Give the file a different filename after it's uploaded to the org with alias "my-scratch":
-
-    $ sf create file --file resources/astro.png --title AstroOnABoat.png --target-org my-scratch
-
-  Attach the file to a record in the org:
-
-    $ sf create file --file path/to/astro.png --parent-id a03fakeLoJWPIA3
+```bash
+sf create file --file path/to/file --target-org your-org
 ```
 
-## `sf remove assignments`
-
-Summary of a command.
+**Example**: Upload an image and attach it to a record:
 
+```bash
+sf create file --file assets/logo.png --title "Company Logo" --parent-id 001XXXXXXXXXXXXXXX --target-org production
 ```
-USAGE
-  $ sf remove assignments -b PermissionSet|PermissionSetGroup|Group... -u <value>... -o <value> [--json] [--flags-dir
-    <value>] [-n <value>]
-
-FLAGS
-  -b, --object=<option>...    (required) The object for which the assignment will be removed.
-                              <options: PermissionSet|PermissionSetGroup|Group>
-  -n, --name=<value>          Description of a flag.
-  -o, --target-org=<value>    (required) Username or alias of the target org. Not required if the `target-org`
-                              configuration variable is already set.
-  -u, --usernames=<value>...  (required) The list of usernames to be unassigned from the selected object. If in a
-                              sandbox, the script will look for "usename" and "username".sandbox for unassignment.
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Summary of a command.
 
-  More information about a command. Don't repeat the summary.
+### `sf remove assignments`
 
-EXAMPLES
-  $ sf remove assignments
+Efficiently manage user permissions by removing assignments from users. Great for cleaning up access during user offboarding!
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  Description of a flag.
-
-    More information about a flag. Don't repeat the summary.
+```bash
+sf remove assignments --object PermissionSet --usernames user@example.com --target-org your-org
 ```
 
-## `sf reporton deployment`
-
-Summary of a command.
+**Example**: Remove multiple permission sets from multiple users:
 
+```bash
+sf remove assignments --object PermissionSet --usernames user1@example.com user2@example.com --target-org production
 ```
-USAGE
-  $ sf reporton deployment -o <value> -d <value> [--json] [--flags-dir <value>] [-a]
 
-FLAGS
-  -a, --awaitcompletion       If the aplication should respond every 30 sec until the deployment is complete.
-  -d, --deploymentid=<value>  (required) The id of the deployment that we want to report on.
-  -o, --target-org=<value>    (required) Username or alias of the target org. Not required if the `target-org`
-                              configuration variable is already set.
+## 🧪 Development
 
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
+To contribute to SF-CIUtils, follow these steps:
 
-DESCRIPTION
-  Summary of a command.
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/marsson/sf-ciutils.git
+   ```
 
-  More information about a command. Don't repeat the summary.
+2. Install dependencies:
+   ```bash
+   yarn install
+   ```
 
-EXAMPLES
-  $ sf reporton deployment
-```
+3. Build the plugin:
+   ```bash
+   yarn build
+   ```
+
+4. Link to your local Salesforce CLI:
+   ```bash
+   sf plugins link .
+   ```
 
-## `sf validate repository metadata`
+5. Run tests:
+   ```bash
+   yarn test
+   ```
 
-Summary of a command.
+## 🤝 Contributing
 
-```
-USAGE
-  $ sf validate repository metadata -o <value> -f <value> [--json] [--flags-dir <value>] [-n <value>]
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
 
-FLAGS
-  -f, --folder=<value>      (required) The path to the deployment folder (ex. force-app/main/default/obects).
-  -n, --name=<value>        Description of a flag.
-  -o, --target-org=<value>  (required) Username or alias of the target org. Not required if the `target-org`
-                            configuration variable is already set.
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
 
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
+## 📝 License
 
-DESCRIPTION
-  Summary of a command.
+This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.
 
-  More information about a command. Don't repeat the summary.
+## 🙏 Acknowledgments
 
-EXAMPLES
-  $ sf validate repository metadata
+- Thanks to the Salesforce CLI team for their amazing work
+- Shoutout to all the contributors who have helped make this project better
+- Special thanks to the Salesforce developer community for their continuous support
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  Description of a flag.
+---
 
-    More information about a flag. Don't repeat the summary.
-```
-<!-- commandsstop -->
+Happy coding! May your deployments be swift and your validations pass on the first try! 🎉