sf-plugin-permission-sets 0.3.0 → 0.4.0

package/LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Isaac Ferreira
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -21,6 +21,7 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Modes](#modes)
 - [Validations](#validations)
 - [Commands](#commands)
+- [GitHub Actions](#github-actions)
 - [Inspiration & equivalents](#inspiration--equivalents)
 - [Versioning](#versioning)
 - [Architecture](#architecture)
@@ -36,7 +37,7 @@ This plugin makes the desired state **declarative and reviewable**:
 - ✅ **Single source of truth:** the YAML in git is authoritative, and the org is reconciled to it.
 - ✅ **Plan before apply:** see exactly what will be added/removed before anything changes.
 - ✅ **Safe by default:** deletions are opt-in and guarded by a delete threshold.
-- ✅ **CI-native:** fully offline `check`, exit codes for gating, and `--json` on every command.
+- ✅ **CI-native:** `check` needs no org, exit codes for gating, and `--json` on every command.
 - ✅ **Flexible at the edges:** pick your file layout (by permission set or by user) and your sync mode.
 - ✅ **GitOps for access, the SFDX way:** assignments live in source and ship through the same git and CI pipeline as your metadata, instead of being clicked into Setup by hand.
 - ✅ **Fewer hands in Setup for higher environments:** because access is applied from git through CI, fewer people need direct Setup access in UAT and production, and every change is a reviewed pull request with a git audit trail.
@@ -53,7 +54,7 @@ Or pin a version:
 sf plugins install sf-plugin-permission-sets@x.y.z
 ```
 
-Requires Salesforce CLI (`sf`) and Node.js 18+.
+Requires Salesforce CLI (`sf`) and Node.js 20+.
 
 ## Quick start
 
@@ -61,7 +62,7 @@ Requires Salesforce CLI (`sf`) and Node.js 18+.
 # 1. Bootstrap YAML from an existing org (so you don't start from scratch)
 sf ps export --target-org dev --output-file permissions.yml
 
-# 2. Edit the files, commit, open a PR. Validate offline, no org needed:
+# 2. Edit the files, commit, open a PR. Check them, no org needed:
 sf ps check --file "./permissions/*.yml"
 
 # 3. Validate against a real org (do the users/permission sets exist?)
@@ -79,7 +80,7 @@ sf ps apply --file "./permissions/*.yml" --target-org prod --mode sync
 
 ## Permission files
 
-You point every command at one or more YAML files with `--file` (alias `-f`).
+`check`, `validate`, `plan`, and `apply` read one or more YAML files with `--file` (alias `-f`). (`export` writes YAML rather than reading it, so there `-f` is the output file.)
 
 Multiple files are merged into one model, so splitting by team is encouraged. The files contain **only declarative data**: knobs like sync mode and exclusions are CLI flags (see [Commands](#commands)), so there's no separate config format to learn yet. Each top-level key is unique within a file, and `check` flags duplicates.
 
@@ -130,7 +131,7 @@ users:
         expiration: 2026-09-30T00:00:00Z
 ```
 
-Expiration is a property of the grant, so `plan` and `apply` treat a changed `expiration` on an already-assigned target as an **update** (the `~` line), not an add or a remove. Updates ride with the additive half: they run in `additive` and `sync` modes and never count against `--max-deletes`. Permission set **licenses** cannot expire (Salesforce has no expiration on `PermissionSetLicenseAssign`), so the object form is rejected there. `export` writes the object form for any assignment that currently has an expiration in the org.
+Expiration is a property of the grant, so `plan` and `apply` treat a changed `expiration` on an already-assigned target as an **update** (the `~` line, which shows the `old → new` transition), not an add or a remove. Updates ride with the additive half: they run in `additive` and `sync` modes and never count against `--max-deletes`. Permission set **licenses** cannot expire (Salesforce has no expiration on `PermissionSetLicenseAssign`), so the object form is rejected there. `export` writes the object form for any assignment that currently has an expiration in the org.
 
 The `--file` flag is repeatable and the plugin expands globs itself, so all of these work:
 
@@ -187,19 +188,19 @@ A run performs three operations: **add** missing assignments, **update** changed
 | `additive`    | ✅           | ✅                  | ❌                 | **Default.** Grant access, never revoke. Safe rollout.                |
 | `destructive` | ❌           | ❌                  | ✅                 | Prune/revoke access that isn't declared, without granting anything new. |
 
-`plan` always shows the *full* picture (adds, expiration updates, **and** would-be removes) regardless of mode, so you can preview the impact before running it. Whatever the chosen mode won't act on is surfaced as **drift**.
+`plan` and `apply` preview and act on exactly what the selected mode covers, so the body shows only those operations and what `plan` shows is what `apply` does. Anything the mode won't touch (an undeclared assignment under `additive`, a missing grant under `destructive`) is reported beneath the plan as **drift**, naming the mode that would include it. `sync` covers everything, so it never reports drift.
 
 ## Validations
 
-Every run checks the files first. `check` runs the offline checks with no org, and `validate` adds the org-side checks. When files merge, most overlaps are unions rather than errors.
+Every run checks the files first. `check` runs the file checks with no org, and `validate` adds the org-side checks. When files merge, most overlaps are unions rather than errors.
 
 | Situation | Checked by | Severity | Result |
 | --- | --- | :---: | --- |
-| Same user in two files with different targets | `check` (offline) | ✅ ok | Merged into one model, the point of slicing |
-| Same target listed twice for a user | `check` (offline) | ⚠️ warning | Deduped |
-| A user with no scopes, or an empty list | `check` (offline) | ⚠️ warning | Ignored as a no-op |
-| Same username key appears twice in one file | `check` (offline) | ❌ error | Rejected, the intent is ambiguous |
-| Declared user, permission set, group, or license missing or not unique | `validate` (online) | ❌ error | Run fails before any change |
+| Same user in two files with different targets | `check` | ✅ ok | Merged into one model, the point of slicing |
+| Same target listed twice for a user | `check` | ⚠️ warning | Deduped |
+| A user with no scopes, or an empty list | `check` | ⚠️ warning | Ignored as a no-op |
+| Same username key appears twice in one file | `check` | ❌ error | Rejected, the intent is ambiguous |
+| Declared user, permission set, group, or license missing or not unique | `validate` | ❌ error | Run fails before any change |
 
 ## Commands
 
@@ -213,7 +214,7 @@ Every run checks the files first. `check` runs the offline checks with no org, a
 
 ### `sf ps check`
 
-Fully offline: runs in any CI job or pre-commit hook without org credentials.
+Needs no org: runs in any CI job or pre-commit hook without org credentials.
 
 ```
 USAGE
@@ -241,7 +242,7 @@ FLAGS
   -o, --target-org=<org>   (required) Org to resolve against.
   -f, --file=<glob>...     (required) YAML file(s) to read. Repeatable, globs expanded by the plugin.
 
-Runs all offline checks, then verifies that every user (active), permission set,
+Runs everything `check` does, then verifies that every user (active), permission set,
 group, and license referenced actually exists and resolves uniquely.
 ```
 
@@ -249,71 +250,211 @@ group, and license referenced actually exists and resolves uniquely.
 
 ```
 USAGE
-  $ sf ps plan -o <org> -f <glob>... [--mode <value>] [--json]
+  $ sf ps plan -o <org> -f <glob>... [--mode <value>] [--show-unchanged]
+               [--out <file>] [--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]
+  --show-unchanged         List assignments that already match, instead of only counting them.
+  --out=<file>             Write the computed change set to a plan file that `apply` can run verbatim.
 ```
 
-Example output:
+With `--out` the plan is also saved to a file: the resolved change set (adds, updates, removes with their record ids), the mode it was computed for, and the org it targets. Feed that file to `apply --plan` to execute exactly what you reviewed, with no recomputation. See [Saved plans](#saved-plans).
+
+The body shows only what the mode will do, and unchanged assignments are summarized as a count (pass `--show-unchanged` to list them). The default `additive` run previews only what it grants, and reports the undeclared assignment it won't remove as drift:
 
 ```text
-$ sf ps plan -o prod --mode sync
+$ sf ps plan -o prod -f "permissions/*.yml"
 
 Permission Set Assignments Plan
-Org: prod (00D5g0000000abcEAA)   Mode: sync
+Org: prod (00D5g0000000abcEAA)   Mode: additive
 
-permissionSets:
+Permission Sets
+  Report_Builder
+    + jdoe@acme.com
   Sales_Manager
     + asmith@acme.com
-    ~ csmith@acme.com (expires 2026-12-31T23:59:59Z)
-    - bwayne@acme.com        (undeclared, will be removed)
-    = jdoe@acme.com          (no change)
+    ~ csmith@acme.com   expires 2026-12-31T23:59:59Z → 2027-06-30T23:59:59Z
+
+Plan: 2 to add, 1 to update. 3 users affected.
+Drift: 1 undeclared assignment not removed in additive mode. Run --mode sync to remove it.
+Unchanged: 4 assignments (--show-unchanged to list).
+
+Next: sf ps apply -o prod -f "permissions/*.yml"
+```
+
+The same files under `--mode sync` act on that drift too, so the removal now appears in the body and the drift line is gone:
+
+```text
+$ sf ps plan -o prod -f "permissions/*.yml" --mode sync
+
+Permission Set Assignments Plan
+Org: prod (00D5g0000000abcEAA)   Mode: sync
+
+Permission Sets
   Report_Builder
     + jdoe@acme.com
+  Sales_Manager
+    + asmith@acme.com
+    ~ csmith@acme.com   expires 2026-12-31T23:59:59Z → 2027-06-30T23:59:59Z
+    - bwayne@acme.com
 
-permissionSetGroups:
-  Sales_Team_Bundle          (no changes)
+Plan: 2 to add, 1 to update, 1 to remove. 4 users affected.
+Unchanged: 4 assignments (--show-unchanged to list).
 
-Plan: 2 to add, 1 to update, 1 to remove, 1 unchanged.
-► Review, then run:  sf ps apply -o prod --mode sync
+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] [--no-prompt] [--json]
+  $ sf ps apply -o <org> (-f <glob>... | --plan <file>) [--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.
+  -f, --file=<glob>...     YAML file(s) to read. Repeatable, globs expanded by the plugin.
+  --plan=<file>            Apply a saved plan file from `plan --out` instead of re-reading YAML.
   --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).
 ```
 
+Provide exactly one source: `--file` (read and diff the YAML now) or `--plan` (run a saved plan). They cannot be combined, and `--mode` cannot accompany `--plan` (the plan already carries its mode). `--max-deletes`, `--dry-run`, and `--no-prompt` apply to both.
+
 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.
 
+#### Saved plans
+
+`plan --out` and `apply --plan` split review from execution, so what you approve is exactly what runs:
+
+```bash
+sf ps plan  -o prod -f "permissions/*.yml" --mode sync --out prod.plan
+# ... review prod.plan, get sign-off ...
+sf ps apply -o prod --plan prod.plan
+```
+
+Without a saved plan, `apply` recomputes from the files: it re-reads the YAML, re-resolves every reference to an org id, and re-diffs against live state. Anything that changed since you ran `plan` (an edited file, a renamed permission set, another admin's assignment) silently changes what `apply` does. A saved plan freezes the resolved change set, so `apply --plan` executes those exact records with no recomputation.
+
+Guardrails:
+
+- `apply --plan` refuses a plan built for a different org (the plan records the org id).
+- It refuses a plan file it cannot parse or whose format version it does not recognize.
+- The plan is executed as recorded. If the org drifted after the plan was written, individual records may fail (a removed target, an already-deleted assignment); those surface as per-record failures in the outcome report rather than aborting the run. Re-run `plan` to get a fresh plan when in doubt.
+
 ### `sf ps export`
 
-Read-only. Snapshots the org's current assignments into a single YAML file you can commit and then feed back into the other commands.
+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.
 
 ```
 USAGE
-  $ sf ps export -o <org> --output-file <file> [--json]
+  $ sf ps export -o <org> [-f <file>] [--user <username>...]
+                 [--kind <scope>...] [--json]
 
 FLAGS
   -o, --target-org=<org>   (required) Org to read assignments from.
-  --output-file=<file>     (required) Path of the YAML file to write. Parent directories are created; an existing file is overwritten.
+  -f, --output-file=<file> Path of the YAML file to write. Parent directories are created; an existing file is overwritten. Omit to write to stdout.
+  --user=<username>...      Only export these users. Repeatable, matched on exact username.
+  --kind=<scope>...         Only export these scopes: permissionSets | permissionSetGroups | permissionSetLicenses. Repeatable.
 ```
 
 It exports every assignable permission set, group, and license assignment held by active users, keyed by username, so the result is immediately valid input for `check`, `validate`, `plan`, and `apply`. Profile-owned permission sets and inactive users are skipped.
 
+With `--output-file` the command writes the file and prints a one-line summary. Omit the flag and the YAML goes to stdout instead, byte-for-byte identical to what the file would contain, so it pipes and diffs cleanly: in that mode only the document reaches stdout and warnings go to stderr, so there is nothing to strip. Under `--json` the envelope is the only thing on stdout, and when `--output-file` is omitted the document comes back in its `content` field.
+
+```bash
+# Diff the org's live state against a committed snapshot
+sf ps export -o prod | diff - permissions/prod.yml
+
+# Redirect a scoped snapshot to a file of your choosing
+sf ps export -o prod --user jdoe@acme.com > jdoe.yml
+```
+
+By default the whole org is exported. `--user` and `--kind` narrow the snapshot: pass either to scope it down, and pass both to intersect (the named users, restricted to the named scopes). Values within a flag are a union, so `--user jdoe@acme.com --user asmith@acme.com` exports both. The `--kind` values are the same scope keys the file uses, so `--kind permissionSetLicenses` reads back exactly the `permissionSetLicenses:` block.
+
+```bash
+# Snapshot one team's permission sets and groups only
+sf ps export -o prod --output-file team.yml \
+  --user jdoe@acme.com --user asmith@acme.com \
+  --kind permissionSets --kind permissionSetGroups
+```
+
+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.
+
+## GitHub Actions
+
+Two dead-simple workflows: check pull requests to main with no org, then apply on merge.
+
+**1. Check pull requests to main** (no org, no secrets):
+
+```yaml
+# .github/workflows/permissions-check.yml
+name: permissions-check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+
+      - name: Install Salesforce CLI
+        run: npm install --global @salesforce/cli
+
+      - name: Install the plugin
+        run: sf plugins install sf-plugin-permission-sets
+
+      - name: Check the permission files
+        run: sf ps check --file "permissions/*.yml"
+```
+
+**2. Apply on merge to main** (needs org auth):
+
+```yaml
+# .github/workflows/permissions-apply.yml
+name: permissions-apply
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  apply:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+
+      - name: Install Salesforce CLI
+        run: npm install --global @salesforce/cli
+
+      - name: Install the plugin
+        run: sf plugins install sf-plugin-permission-sets
+
+      - name: Log in to the org
+        run: echo '${{ secrets.SFDX_AUTH_URL }}' | sf org login sfdx-url --sfdx-url-stdin --alias prod
+
+      - name: Apply the assignments
+        run: sf ps apply --file "permissions/*.yml" --target-org prod --mode sync --no-prompt
+```
+
+Get the auth URL once with `sf org display --verbose --target-org prod`, copy the `Sfdx Auth Url` value, and save it as a repository secret named `SFDX_AUTH_URL`.
+
+Want the diff on the PR before merging? Add a `sf ps plan --file "permissions/*.yml" --target-org prod` step (it needs the same org auth) to the check workflow.
+
 ## Inspiration & equivalents
 
 This plugin's command surface borrows ideas from tools you already know:
@@ -354,11 +495,8 @@ gh release create v0.2.0 --target main --title v0.2.0 --notes "Add ps export"
 | dist-tag | Published by | Install |
 | --- | --- | --- |
 | `latest` | manual release with a normal tag like `v1.2.0` | `sf plugins install sf-plugin-permission-sets` |
-| `next` | manual release with a hyphenated tag like `v1.3.0-beta.1` | `sf plugins install sf-plugin-permission-sets@next` |
 | `dev` | automatic on every push to `main` | `sf plugins install sf-plugin-permission-sets@dev` |
 
-The `next` tag is selected whenever the version contains a hyphen, not by GitHub's prerelease checkbox.
-
 ## Architecture
 
 The plugin is layered so every command reuses the same core. Commands stay thin, services hold the orchestration, core holds the reusable primitives, and a thin adapter layer isolates the Salesforce SDK.
@@ -379,9 +517,11 @@ The plugin is layered so every command reuses the same core. Commands stay thin,
 | `load` | Expand globs, run parse then validate then normalize per file, and merge by union. |
 | `resolve` | Pure rules that turn declared references and the org's answers into findings, plus id lookups for assigning. No SOQL: the adapter owns that. |
 | `diff` | The desired model vs. the org's current state, producing adds, removes, and unchanged. |
+| `mode` | Scope a diff to what a reconcile mode acts on, plus the drift it leaves alone. |
 | `report` | Format a diff as a plan. |
+| `plan-file` | Serialize and parse a saved plan: the frozen change set `apply --plan` runs. |
 
-Commands are slices of one pipeline. `check` runs the offline **load** stage only. `validate` adds **resolve**: it looks the declared references up through the `OrgClient` port (the adapter builds the SOQL) and evaluates the org's answers with resolve's pure rules. `export` runs in the opposite direction: it **fetch**es the org's current assignments through the port and **serialize**s them straight back to YAML, skipping load entirely. `apply` is the full pipeline: load, resolve to ids, **fetch** current state, **diff**, then insert and delete through the Collections API per the mode (guarded by `--max-deletes` and a confirmation). `plan` is that same pipeline stopping before the DML: load, resolve to ids, **fetch** current state, **diff**, and report, the same preview `apply --dry-run` produces.
+Commands are slices of one pipeline. `check` runs the **load** stage only, with no org. `validate` adds **resolve**: it looks the declared references up through the `OrgClient` port (the adapter builds the SOQL) and evaluates the org's answers with resolve's pure rules. `export` runs in the opposite direction: it **fetch**es the org's current assignments through the port and **serialize**s them straight back to YAML, skipping load entirely. `apply` is the full pipeline: load, resolve to ids, **fetch** current state, **diff**, then insert and delete through the Collections API per the mode (guarded by `--max-deletes` and a confirmation). `plan` is that same pipeline stopping before the DML: load, resolve to ids, **fetch** current state, **diff**, and report, the same preview `apply --dry-run` produces. `plan --out` freezes that resolved change set to a file, and `apply --plan` runs it verbatim, skipping load, resolve, and diff.
 
 ## License
 

package/lib/adapters/connection-org-client.d.ts

@@ -1,14 +1,18 @@
 import { Connection } from '@salesforce/core';
-import { ActualAssignment, AssignmentOutcome, AssignmentUpdate, DesiredAssignment, Kind, OrgTarget, OrgUser, ResolvedAddition, TargetRef } from '../core/model.js';
-import { OrgClient } from '../services/adapters/org-client.js';
+import { ActualAssignment, AssignmentFilter, AssignmentOutcome, AssignmentUpdate, DesiredAssignment, Kind, OrgTarget, OrgUser, ResolvedAddition, TargetRef } from '../core/index.js';
+import { OrgClient } from '../services/adapters/index.js';
 /** Adapter backing OrgClient with a Salesforce Connection. autoFetchQuery pages past 2000 rows. */
 export declare class ConnectionOrgClient implements OrgClient {
     private readonly connection;
     constructor(connection: Connection);
     findUsers(usernames: string[]): Promise<OrgUser[]>;
     findTargets(kind: Kind, names: string[]): Promise<OrgTarget[]>;
-    listAssignments(): Promise<DesiredAssignment[]>;
+    listAssignments(filter?: AssignmentFilter): Promise<DesiredAssignment[]>;
+    private listMemberships;
+    private listLicenses;
     currentAssignments(targets: TargetRef[]): Promise<ActualAssignment[]>;
+    private membershipAssignments;
+    private licenseAssignments;
     addAssignments(additions: ResolvedAddition[]): Promise<AssignmentOutcome[]>;
     updateAssignments(updates: AssignmentUpdate[]): Promise<AssignmentOutcome[]>;
     removeAssignments(removals: ActualAssignment[]): Promise<AssignmentOutcome[]>;

package/lib/adapters/connection-org-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-org-client.d.ts","sourceRoot":"","sources":["../../src/adapters/connection-org-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACH,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,IAAI,EACJ,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,SAAS,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AA6J/D,mGAAmG;AACnG,qBAAa,mBAAoB,YAAW,SAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,UAAU;IAE7C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQlD,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAS9D,eAAe,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA8C/C,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA0DrE,cAAc,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAoB3E,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAoB5E,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAuB5E,KAAK;CAItB"}
+{"version":3,"file":"connection-org-client.d.ts","sourceRoot":"","sources":["../../src/adapters/connection-org-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,IAAI,EACJ,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,SAAS,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AA6J1D,mGAAmG;AACnG,qBAAa,mBAAoB,YAAW,SAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,UAAU;IAE7C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQlD,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAS9D,eAAe,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAkBvE,eAAe;YAoCf,YAAY;IAgBb,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YA4BpE,qBAAqB;YAsBrB,kBAAkB;IAUnB,cAAc,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAkB3E,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAkB5E,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAmB5E,KAAK;CAItB"}

package/lib/adapters/connection-org-client.js

@@ -116,43 +116,64 @@ export class ConnectionOrgClient {
         const records = await this.query(`SELECT Id, ${field} FROM ${sobject} WHERE ${field} IN (${inList(names)})`);
         return records.map((record) => ({ id: record.Id, name: record[field] }));
     }
-    async listAssignments() {
-        const [memberships, licenses] = await Promise.all([
-            this.query('SELECT Id, Assignee.Username, PermissionSet.Name, PermissionSetGroup.DeveloperName, PermissionSetGroupId, ExpirationDate ' +
-                'FROM PermissionSetAssignment ' +
-                'WHERE Assignee.IsActive = true AND PermissionSet.IsOwnedByProfile = false'),
-            this.query('SELECT Id, Assignee.Username, PermissionSetLicense.DeveloperName ' +
-                'FROM PermissionSetLicenseAssign ' +
-                'WHERE Assignee.IsActive = true'),
-        ]);
-        const assignments = [];
-        for (const record of memberships) {
+    async listAssignments(filter) {
+        const kinds = filter?.kinds;
+        const wantsPermissionSet = !kinds || kinds.includes('permissionSet');
+        const wantsGroup = !kinds || kinds.includes('permissionSetGroup');
+        const wantsLicense = !kinds || kinds.includes('permissionSetLicense');
+        const tasks = [];
+        if (wantsPermissionSet || wantsGroup) {
+            tasks.push(this.listMemberships(filter?.usernames, wantsPermissionSet, wantsGroup));
+        }
+        if (wantsLicense) {
+            tasks.push(this.listLicenses(filter?.usernames));
+        }
+        const results = await Promise.all(tasks);
+        return results.flat();
+    }
+    async listMemberships(usernames, wantsPermissionSet, wantsGroup) {
+        const clauses = [
+            'Assignee.IsActive = true',
+            'PermissionSet.IsOwnedByProfile = false',
+        ];
+        if (usernames)
+            clauses.push(`Assignee.Username IN (${inList(usernames)})`);
+        if (!wantsGroup)
+            clauses.push('PermissionSetGroupId = null');
+        if (!wantsPermissionSet)
+            clauses.push('PermissionSetGroupId != null');
+        const soql = 'SELECT Id, Assignee.Username, PermissionSet.Name, PermissionSetGroup.DeveloperName, PermissionSetGroupId, ExpirationDate ' +
+            `FROM PermissionSetAssignment WHERE ${clauses.join(' AND ')}`;
+        const records = await this.query(soql);
+        return records.map((record) => {
             const expiration = record.ExpirationDate ? { expiration: record.ExpirationDate } : {};
-            if (record.PermissionSetGroupId && record.PermissionSetGroup) {
-                assignments.push({
+            return record.PermissionSetGroupId && record.PermissionSetGroup
+                ? {
                     assignee: record.Assignee.Username,
                     kind: 'permissionSetGroup',
                     target: record.PermissionSetGroup.DeveloperName,
                     ...expiration,
-                });
-            }
-            else {
-                assignments.push({
+                }
+                : {
                     assignee: record.Assignee.Username,
                     kind: 'permissionSet',
                     target: record.PermissionSet.Name,
                     ...expiration,
-                });
-            }
-        }
-        for (const record of licenses) {
-            assignments.push({
-                assignee: record.Assignee.Username,
-                kind: 'permissionSetLicense',
-                target: record.PermissionSetLicense.DeveloperName,
-            });
-        }
-        return assignments;
+                };
+        });
+    }
+    async listLicenses(usernames) {
+        const clauses = ['Assignee.IsActive = true'];
+        if (usernames)
+            clauses.push(`Assignee.Username IN (${inList(usernames)})`);
+        const soql = 'SELECT Id, Assignee.Username, PermissionSetLicense.DeveloperName ' +
+            `FROM PermissionSetLicenseAssign WHERE ${clauses.join(' AND ')}`;
+        const records = await this.query(soql);
+        return records.map((record) => ({
+            assignee: record.Assignee.Username,
+            kind: 'permissionSetLicense',
+            target: record.PermissionSetLicense.DeveloperName,
+        }));
     }
     async currentAssignments(targets) {
         const permissionSetIds = targets.filter((ref) => ref.kind === 'permissionSet').map((ref) => ref.id);
@@ -167,44 +188,52 @@ export class ConnectionOrgClient {
         if (memberClauses.length > 0) {
             const soql = 'SELECT Id, Assignee.Username, PermissionSet.Name, PermissionSetGroup.DeveloperName, PermissionSetGroupId, ExpirationDate ' +
                 `FROM PermissionSetAssignment WHERE ${memberClauses.join(' OR ')}`;
-            tasks.push(this.query(soql).then((records) => records.map((record) => {
-                const expiration = record.ExpirationDate ? { expiration: record.ExpirationDate } : {};
-                return record.PermissionSetGroupId && record.PermissionSetGroup
-                    ? {
-                        recordId: record.Id,
-                        assignee: record.Assignee.Username,
-                        kind: 'permissionSetGroup',
-                        target: record.PermissionSetGroup.DeveloperName,
-                        ...expiration,
-                    }
-                    : {
-                        recordId: record.Id,
-                        assignee: record.Assignee.Username,
-                        kind: 'permissionSet',
-                        target: record.PermissionSet.Name,
-                        ...expiration,
-                    };
-            })));
+            tasks.push(this.membershipAssignments(soql));
         }
         if (licenseIds.length > 0) {
             const soql = 'SELECT Id, Assignee.Username, PermissionSetLicense.DeveloperName ' +
                 `FROM PermissionSetLicenseAssign WHERE PermissionSetLicenseId IN (${inList(licenseIds)})`;
-            tasks.push(this.query(soql).then((records) => records.map((record) => ({
-                recordId: record.Id,
-                assignee: record.Assignee.Username,
-                kind: 'permissionSetLicense',
-                target: record.PermissionSetLicense.DeveloperName,
-            }))));
+            tasks.push(this.licenseAssignments(soql));
         }
         const results = await Promise.all(tasks);
         return results.flat();
     }
+    async membershipAssignments(soql) {
+        const records = await this.query(soql);
+        return records.map((record) => {
+            const expiration = record.ExpirationDate ? { expiration: record.ExpirationDate } : {};
+            return record.PermissionSetGroupId && record.PermissionSetGroup
+                ? {
+                    recordId: record.Id,
+                    assignee: record.Assignee.Username,
+                    kind: 'permissionSetGroup',
+                    target: record.PermissionSetGroup.DeveloperName,
+                    ...expiration,
+                }
+                : {
+                    recordId: record.Id,
+                    assignee: record.Assignee.Username,
+                    kind: 'permissionSet',
+                    target: record.PermissionSet.Name,
+                    ...expiration,
+                };
+        });
+    }
+    async licenseAssignments(soql) {
+        const records = await this.query(soql);
+        return records.map((record) => ({
+            recordId: record.Id,
+            assignee: record.Assignee.Username,
+            kind: 'permissionSetLicense',
+            target: record.PermissionSetLicense.DeveloperName,
+        }));
+    }
     async addAssignments(additions) {
         const batches = additionBatches(additions);
-        const settled = await Promise.all(batches.map((batch) => this.connection.create(batch.sobject, batch.records, { allOrNone: false }).then((results) => ({
-            batch,
-            results: results,
-        }))));
+        const settled = await Promise.all(batches.map(async (batch) => {
+            const results = await this.connection.create(batch.sobject, batch.records, { allOrNone: false });
+            return { batch, results: results };
+        }));
         const outcomes = [];
         for (const { batch, results } of settled) {
             batch.additions.forEach((addition, index) => {
@@ -215,10 +244,10 @@ export class ConnectionOrgClient {
     }
     async updateAssignments(updates) {
         const batches = updateBatches(updates);
-        const settled = await Promise.all(batches.map((batch) => this.connection.update(batch.sobject, batch.records, { allOrNone: false }).then((results) => ({
-            batch,
-            results: results,
-        }))));
+        const settled = await Promise.all(batches.map(async (batch) => {
+            const results = await this.connection.update(batch.sobject, batch.records, { allOrNone: false });
+            return { batch, results: results };
+        }));
         const outcomes = [];
         for (const { batch, results } of settled) {
             batch.updates.forEach((update, index) => {
@@ -229,9 +258,11 @@ export class ConnectionOrgClient {
     }
     async removeAssignments(removals) {
         const batches = removalBatches(removals);
-        const settled = await Promise.all(batches.map((batch) => this.connection
-            .destroy(batch.sobject, batch.removals.map((removal) => removal.recordId), { allOrNone: false })
-            .then((results) => ({ batch, results: results }))));
+        const settled = await Promise.all(batches.map(async (batch) => {
+            const recordIds = batch.removals.map((removal) => removal.recordId);
+            const results = await this.connection.destroy(batch.sobject, recordIds, { allOrNone: false });
+            return { batch, results: results };
+        }));
         const outcomes = [];
         for (const { batch, results } of settled) {
             batch.removals.forEach((removal, index) => {