sf-plugin-permission-sets 0.0.0-dev.73 → 0.0.0-dev.75

package/README.md

@@ -15,6 +15,7 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 
 - [Why](#why)
 - [Install](#install)
+- [Org permissions](#org-permissions)
 - [Quick start](#quick-start)
 - [Permission files](#permission-files)
 - [Organizing files](#organizing-files)
@@ -22,10 +23,10 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Validations](#validations)
 - [Commands](#commands)
 - [GitHub Actions](#github-actions)
-- [Inspiration & equivalents](#inspiration--equivalents)
 - [Versioning](#versioning)
 - [Architecture](#architecture)
 - [Development](#development)
+- [License](#license)
 
 ---
 
@@ -57,6 +58,25 @@ sf plugins install sf-plugin-permission-sets@x.y.z
 
 Requires Salesforce CLI (`sf`) and Node.js 22.13+.
 
+## Org permissions
+
+What the user behind `--target-org` needs:
+
+| Command | API Enabled | View Setup and Configuration | View Roles and Role Hierarchy | Assign Permission Sets |
+| --- | :---: | :---: | :---: | :---: |
+| `sf ps check` | - | - | - | - |
+| `sf ps validate` | ✓ | ✓ | ✓ | - |
+| `sf ps plan` | ✓ | ✓ | ✓ | - |
+| `sf ps export` | ✓ | ✓ | ✓ | - |
+| `sf ps apply` | ✓ | ✓ | ✓ | ✓ |
+
+✓ Required, - Not required.
+
+Two permission sets, so a pull request job cannot change the org:
+
+- [PS_Plugin_Read](setup/permissionsets/PS_Plugin_Read.permissionset-meta.xml): reads permission set assignments.
+- [PS_Plugin_Write](setup/permissionsets/PS_Plugin_Write.permissionset-meta.xml): reads and modifies permission set assignments.
+
 ## Quick start
 
 ```bash
@@ -217,8 +237,8 @@ Every run checks the files first. `check` runs the file checks with no org, and
 | `sf ps check`    | Static analysis of the files alone: schema, duplicates, conflicts, identifier shape. No org, no auth. |
 | `sf ps validate` | Everything `check` does, plus resolving every user/permission set against the org. |
 | `sf ps plan`     | Compute and display the change set: a read-only preview of what `apply` would do. |
-| `sf ps apply`    | Reconcile the org. Honors `--mode`, prompts before deletes, enforces guardrails. |
 | `sf ps export`   | Generate YAML from the current org state to bootstrap adoption.        |
+| `sf ps apply`    | Reconcile the org. Honors `--mode`, prompts before deletes, enforces guardrails. |
 
 ### `sf ps check`
 
@@ -311,27 +331,6 @@ Unchanged: 4 assignments (--show-unchanged to list).
 Next: sf ps apply -o prod -f "permissions/*.yml" --mode sync
 ```
 
-### `sf ps apply`
-
-```
-USAGE
-  $ sf ps apply -o <org> -f <glob>... [--mode <value>]
-                [--max-deletes <n>] [--dry-run] [--show-unchanged] [--no-prompt] [--json]
-
-FLAGS
-  -o, --target-org=<org>   (required)
-  -f, --file=<glob>...     (required) YAML file(s) to read. Repeatable, globs expanded by the plugin.
-  --mode=<value>           additive | destructive | sync   [default: additive]
-  --max-deletes=<n>        Abort if a run would remove more than n assignments. [default: 50]
-  --dry-run                Resolve and diff, print what would happen, change nothing.
-  --show-unchanged         List assignments that already match, instead of only counting them.
-  --no-prompt              Skip the deletion confirmation prompt (for CI).
-```
-
-`apply` recomputes from the files every run: it re-reads the YAML, re-resolves every reference to an org id, and re-diffs against live state, then acts per `--mode`. Run `plan` shortly before `apply` so the preview you review reflects what `apply` will do (an edited file, a renamed permission set, or another admin's change between the two shifts the outcome).
-
-Deletions always prompt for confirmation unless `--no-prompt` is set, and are hard-capped by `--max-deletes` so a bad merge can't unassign your whole org. DML is executed with the sObject Collections API and reports partial successes/failures per record.
-
 ### `sf ps export`
 
 Read-only. Snapshots the org's current assignments as YAML you can commit and then feed back into the other commands. Writes to a file with `--output-file`, or to stdout when that flag is omitted.
@@ -371,10 +370,33 @@ sf ps export -o prod --output-file team.yml \
 
 A requested `--user` that has no matching assignments (a typo, or a user who genuinely holds nothing in scope) is reported as a warning and the export continues with whoever matched, so a mistyped username never masquerades as a clean empty file.
 
+### `sf ps apply`
+
+```
+USAGE
+  $ sf ps apply -o <org> -f <glob>... [--mode <value>]
+                [--max-deletes <n>] [--dry-run] [--show-unchanged] [--no-prompt] [--json]
+
+FLAGS
+  -o, --target-org=<org>   (required)
+  -f, --file=<glob>...     (required) YAML file(s) to read. Repeatable, globs expanded by the plugin.
+  --mode=<value>           additive | destructive | sync   [default: additive]
+  --max-deletes=<n>        Abort if a run would remove more than n assignments. [default: 50]
+  --dry-run                Resolve and diff, print what would happen, change nothing.
+  --show-unchanged         List assignments that already match, instead of only counting them.
+  --no-prompt              Skip the deletion confirmation prompt (for CI).
+```
+
+`apply` recomputes from the files every run: it re-reads the YAML, re-resolves every reference to an org id, and re-diffs against live state, then acts per `--mode`. Run `plan` shortly before `apply` so the preview you review reflects what `apply` will do (an edited file, a renamed permission set, or another admin's change between the two shifts the outcome).
+
+Deletions always prompt for confirmation unless `--no-prompt` is set, and are hard-capped by `--max-deletes` so a bad merge can't unassign your whole org. DML is executed with the sObject Collections API and reports partial successes/failures per record.
+
 ## GitHub Actions
 
 Three small workflows that build on each other: check pull requests with no org at all, validate the same files against the real org, then apply on merge.
 
+Point the pull request workflows at a `PS_Plugin_Read` user and only the merge workflow at `PS_Plugin_Write` (see [Org permissions](#org-permissions)).
+
 **1. Check pull requests to main** (no org, no secrets):
 
 ```yaml
@@ -474,15 +496,6 @@ Workflows 2 and 3 share one secret. Get the auth URL once with `sf org display -
 
 Want the diff on the PR before merging? Add a `sf ps plan --file "permissions/*.yml" --target-org prod` step to workflow 2, right after the login step, so reviewers see the change set that `apply` will carry out on merge.
 
-## Inspiration & equivalents
-
-This plugin's command surface borrows ideas from tools you already know:
-
-- [Terraform](https://developer.hashicorp.com/terraform/docs)
-- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/)
-- [AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/)
-- [Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference.htm)
-
 ## Versioning
 
 Releases follow [semantic versioning](https://semver.org). Snapshots are automatic, real releases are a manual decision.
@@ -563,7 +576,6 @@ cp .env.example .env
 | --- | --- | --- |
 | `PS_TARGET_ORG` | yes | Username or alias of an already-authenticated org. The `plan`, `apply`, and `export` specs run against it. |
 
-
 ## License
 
 BSD-3-Clause © Isaac Ferreira

package/package.json

@@ -126,5 +126,5 @@
     "exports": "./lib/index.js",
     "type": "module",
     "author": "Isaac Ferreira",
-    "version": "0.0.0-dev.73"
+    "version": "0.0.0-dev.75"
 }