sf-plugin-permission-sets 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # sf-plugin-permission-sets
 
-[![NPM](https://img.shields.io/npm/v/sf-plugin-permission-sets.svg?label=sf-plugin-permission-sets)](https://www.npmjs.com/package/sf-plugin-permission-sets) [![Downloads/week](https://img.shields.io/npm/dw/sf-plugin-permission-sets.svg)](https://npmjs.org/package/sf-plugin-permission-sets) [![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)](https://semver.org/#spec-item-4) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/zaclummys/sf-plugin-permission-sets/main/LICENSE.txt)
+[![NPM](https://img.shields.io/npm/v/sf-plugin-permission-sets.svg?label=sf-plugin-permission-sets)](https://www.npmjs.com/package/sf-plugin-permission-sets) [![Downloads/week](https://img.shields.io/npm/dw/sf-plugin-permission-sets.svg)](https://npmjs.org/package/sf-plugin-permission-sets) [![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)](https://semver.org/#spec-item-4) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/zaclummys/sf-plugin-permission-sets/main/LICENSE.md)
 
 > Declarative, GitOps-style management of **permission set assignments** for Salesforce orgs.
 > Define who gets what in version-controlled YAML. The plugin reconciles your org to match it: `plan` then `apply`, just like Terraform.
@@ -25,6 +25,7 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Inspiration & equivalents](#inspiration--equivalents)
 - [Versioning](#versioning)
 - [Architecture](#architecture)
+- [Development](#development)
 
 ---
 
@@ -60,22 +61,22 @@ Requires Salesforce CLI (`sf`) and Node.js 20+.
 
 ```bash
 # 1. Bootstrap YAML from an existing org (so you don't start from scratch)
-sf ps export --target-org dev --output-file permissions.yml
+sf ps export --target-org dev --output-file permissions/dev.yml
 
 # 2. Edit the files, commit, open a PR. Check them, no org needed:
-sf ps check --file "./permissions/*.yml"
+sf ps check --file "permissions/*.yml"
 
 # 3. Validate against a real org (do the users/permission sets exist?)
-sf ps validate --file "./permissions/*.yml" --target-org dev
+sf ps validate --file "permissions/*.yml" --target-org dev
 
 # 4. See what would change
-sf ps plan --file "./permissions/*.yml" --target-org dev
+sf ps plan --file "permissions/*.yml" --target-org dev
 
 # 5. Apply it (additive by default, only adds)
-sf ps apply --file "./permissions/*.yml" --target-org dev
+sf ps apply --file "permissions/*.yml" --target-org dev
 
 # 6. Full reconcile, including removals (opt-in)
-sf ps apply --file "./permissions/*.yml" --target-org prod --mode sync
+sf ps apply --file "permissions/*.yml" --target-org prod --mode sync
 ```
 
 ## Permission files
@@ -250,19 +251,15 @@ group, and license referenced actually exists and resolves uniquely.
 
 ```
 USAGE
-  $ sf ps plan -o <org> -f <glob>... [--mode <value>] [--show-unchanged]
-               [--out <file>] [--json]
+  $ sf ps plan -o <org> -f <glob>... [--mode <value>] [--show-unchanged] [--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.
 ```
 
-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
@@ -311,13 +308,12 @@ Next: sf ps apply -o prod -f "permissions/*.yml" --mode sync
 
 ```
 USAGE
-  $ sf ps apply -o <org> (-f <glob>... | --plan <file>) [--mode <value>]
+  $ 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>...     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.
+  -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.
@@ -325,28 +321,10 @@ FLAGS
   --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.
+`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.
 
-#### 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 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.
@@ -388,7 +366,7 @@ A requested `--user` that has no matching assignments (a typo, or a user who gen
 
 ## GitHub Actions
 
-Two dead-simple workflows: check pull requests to main with no org, then apply on merge.
+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.
 
 **1. Check pull requests to main** (no org, no secrets):
 
@@ -419,7 +397,41 @@ jobs:
         run: sf ps check --file "permissions/*.yml"
 ```
 
-**2. Apply on merge to main** (needs org auth):
+**2. Validate pull requests against the org** (needs org auth):
+
+```yaml
+# .github/workflows/permissions-validate.yml
+name: permissions-validate
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "permissions/**"
+
+jobs:
+  validate:
+    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: Validate the permission files
+        run: sf ps validate --file "permissions/*.yml" --target-org prod
+```
+
+**3. Apply on merge to main** (needs org auth):
 
 ```yaml
 # .github/workflows/permissions-apply.yml
@@ -451,9 +463,9 @@ jobs:
         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`.
+Workflows 2 and 3 share one secret. 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.
+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
 
@@ -502,7 +514,7 @@ gh release create v0.2.0 --target main --title v0.2.0 --notes "Add ps export"
 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.
 
 - **Commands** (`src/commands/ps/`): oclif only. They parse flags, construct the service (wiring in the org adapter when the command needs one), render output, and set the exit code.
-- **Services** (`src/services/`): one per command (`check`, `validate`, `export`, `apply`, and `plan`). Each is a class built from its dependencies and inputs, with a parameterless `run()` that turns the core into a command's behavior. A service also declares the ports it needs from the outside, like the `OrgClient` interface its adapter implements.
+- **Services** (`src/services/`): one per command (`check`, `validate`, `export`, `apply`, and `plan`), plus `resolution`, which the org-facing ones share. Each is a class whose constructor takes only its dependencies (the org client, a confirmation callback), while the per-invocation inputs are `run()` parameters, so one instance serves any number of runs. A service also declares the ports it needs from the outside, like the `OrgClient` interface its adapter implements.
 - **Core** (`src/core/`): the reusable building blocks. Pure, with no `@salesforce/*` imports, so every piece is unit-testable on its own.
 - **Adapters** (`src/adapters/`): the boundary to the outside world. `ConnectionOrgClient` implements the `OrgClient` port (declared in services) with a Salesforce `Connection`, and owns all the SOQL and SObject detail. Services depend on the port, not the SDK, so they test against a fake and stay free of connection detail.
 
@@ -519,9 +531,31 @@ The plugin is layered so every command reuses the same core. Commands stay thin,
 | `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 **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.
+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.
+
+## Development
+
+```bash
+npm ci
+npm run build   # compile and lint
+npm test        # compile, then run the suite
+```
+
+The suite is black-box: every spec spawns the real `sf ps ...` binary. Install the Salesforce CLI first (`npm install -g @salesforce/cli`). The test run links this plugin into `sf` before the first spec and unlinks it at the end.
+
+### Test environment
+
+Tests take their parameters from the environment, never from a committed file. Copy the template and fill it in:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | What it is |
+| --- | --- | --- |
+| `PS_TARGET_ORG` | yes | Username or alias of an already-authenticated org. The `plan`, `apply`, and `export` specs run against it. |
+
 
 ## License
 

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

@@ -1,18 +1,20 @@
 import { Connection } from '@salesforce/core';
-import { ActualAssignment, AssignmentFilter, AssignmentOutcome, AssignmentUpdate, DesiredAssignment, Kind, OrgTarget, OrgUser, ResolvedAddition, TargetRef } from '../core/index.js';
+import { ActualAssignment, AssignmentFilter, AssignmentOutcome, AssignmentUpdate, DesiredAssignment, 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[]>;
+    findPermissionSets(names: string[]): Promise<OrgTarget[]>;
+    findPermissionSetGroups(names: string[]): Promise<OrgTarget[]>;
+    findPermissionSetLicenses(names: string[]): Promise<OrgTarget[]>;
     listAssignments(filter?: AssignmentFilter): Promise<DesiredAssignment[]>;
     private listMemberships;
     private listLicenses;
-    currentAssignments(targets: TargetRef[]): Promise<ActualAssignment[]>;
-    private membershipAssignments;
-    private licenseAssignments;
+    listCurrentAssignments(targets: TargetRef[]): Promise<ActualAssignment[]>;
+    private listMembershipAssignments;
+    private listLicenseAssignments;
     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,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"}
+{"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,EAEjB,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,SAAS,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAgR1D,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;IAMlD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMzD,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAM9D,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMhE,eAAe,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAkBvE,eAAe;YAoBf,YAAY;IAYb,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqBxE,yBAAyB;YAezB,sBAAsB;IAWvB,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

@@ -1,9 +1,3 @@
-/** SObject + naming field per kind. The Salesforce schema knowledge lives here, not in core. */
-const targetObjects = {
-    permissionSet: { sobject: 'PermissionSet', field: 'Name' },
-    permissionSetGroup: { sobject: 'PermissionSetGroup', field: 'DeveloperName' },
-    permissionSetLicense: { sobject: 'PermissionSetLicense', field: 'DeveloperName' },
-};
 /** SObject + foreign-key field to set per kind when assigning. */
 const assignmentObjects = {
     permissionSet: { sobject: 'PermissionSetAssignment', idField: 'PermissionSetId' },
@@ -13,12 +7,121 @@ const assignmentObjects = {
 /** The sObject Collections API caps each create/delete call at 200 records. */
 const collectionBatchSize = 200;
 /** Escape a value for safe inclusion in a SOQL string literal. */
-function soqlLiteral(value) {
+function escapeSoqlLiteral(value) {
     return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
 }
 /** Build a comma-separated, quoted IN list from the values. */
-function inList(values) {
-    return values.map((value) => `'${soqlLiteral(value)}'`).join(', ');
+function buildInList(values) {
+    return values.map((value) => `'${escapeSoqlLiteral(value)}'`).join(', ');
+}
+/** Full membership SOQL for the active, non-profile-owned assignments matching the filter. */
+function buildMembershipQuery(usernames, wantsPermissionSet, wantsGroup) {
+    const clauses = [
+        'Assignee.IsActive = true',
+        'PermissionSet.IsOwnedByProfile = false',
+    ];
+    if (usernames)
+        clauses.push(`Assignee.Username IN(${buildInList(usernames)})`);
+    if (!wantsGroup)
+        clauses.push('PermissionSetGroupId = null');
+    if (!wantsPermissionSet)
+        clauses.push('PermissionSetGroupId != null');
+    return `
+        SELECT
+            Id,
+            Assignee.Username,
+            PermissionSet.Name,
+            PermissionSetGroup.DeveloperName,
+            PermissionSetGroupId,
+            ExpirationDate
+        FROM PermissionSetAssignment
+        WHERE ${clauses.join(' AND ')}
+    `;
+}
+/** Full membership SOQL for the current assignments of the given permission set and group ids. */
+function buildCurrentMembershipQuery(permissionSetIds, groupIds) {
+    const clauses = [];
+    if (permissionSetIds.length > 0)
+        clauses.push(`PermissionSetId IN(${buildInList(permissionSetIds)})`);
+    if (groupIds.length > 0)
+        clauses.push(`PermissionSetGroupId IN(${buildInList(groupIds)})`);
+    return `
+        SELECT
+            Id,
+            Assignee.Username,
+            PermissionSet.Name,
+            PermissionSetGroup.DeveloperName,
+            PermissionSetGroupId,
+            ExpirationDate
+        FROM PermissionSetAssignment
+        WHERE ${clauses.join(' OR ')}
+    `;
+}
+/** Full license SOQL for the active assignments matching the filter. */
+function buildLicenseQuery(usernames) {
+    const clauses = ['Assignee.IsActive = true'];
+    if (usernames)
+        clauses.push(`Assignee.Username IN(${buildInList(usernames)})`);
+    return `
+        SELECT
+            Id,
+            Assignee.Username,
+            PermissionSetLicense.DeveloperName
+        FROM PermissionSetLicenseAssign
+        WHERE ${clauses.join(' AND ')}
+    `;
+}
+/** Full license SOQL for the current assignments of the given license ids. */
+function buildCurrentLicenseQuery(licenseIds) {
+    return `
+        SELECT
+            Id,
+            Assignee.Username,
+            PermissionSetLicense.DeveloperName
+        FROM PermissionSetLicenseAssign
+        WHERE PermissionSetLicenseId IN(${buildInList(licenseIds)})
+    `;
+}
+/** Full SOQL for the users with the given usernames. */
+function buildUserQuery(usernames) {
+    return `
+        SELECT
+            Id,
+            Username,
+            IsActive
+        FROM User
+        WHERE Username IN(${buildInList(usernames)})
+    `;
+}
+/** Full SOQL for the permission sets with the given names. */
+function buildPermissionSetQuery(names) {
+    return `
+        SELECT
+            Id,
+            Name
+        FROM PermissionSet
+        WHERE Name IN(${buildInList(names)})
+    `;
+}
+/** Full SOQL for the permission set groups with the given developer names. */
+function buildPermissionSetGroupQuery(names) {
+    return `
+        SELECT
+            Id,
+            DeveloperName
+        FROM PermissionSetGroup
+        WHERE DeveloperName IN(${buildInList(names)})
+    `;
+}
+/** Full SOQL for the permission set licenses with the given developer names. */
+function buildPermissionSetLicenseQuery(names) {
+    return `
+        SELECT
+            Id,
+            DeveloperName
+        FROM PermissionSetLicense
+        WHERE DeveloperName IN(${buildInList(names)})
+    `;
 }
 /** Split items into chunks of at most `size`. */
 function chunk(items, size) {
@@ -29,7 +132,7 @@ function chunk(items, size) {
     return chunks;
 }
 /** Turn a per-record DML result into a domain outcome, capturing the error message on failure. */
-function outcomeOf(assignment, operation, result) {
+function deriveOutcome(assignment, operation, result) {
     const success = result?.success ?? false;
     const message = result && !result.success ? result.errors.map((error) => error.message).join('; ') : undefined;
     return {
@@ -42,7 +145,7 @@ function outcomeOf(assignment, operation, result) {
     };
 }
 /** Group additions by sObject and chunk them for the Collections API, keeping each record's source. */
-function additionBatches(additions) {
+function buildAdditionBatches(additions) {
     const bySobject = new Map();
     for (const addition of additions) {
         const { sobject } = assignmentObjects[addition.kind];
@@ -64,7 +167,7 @@ function additionBatches(additions) {
     return batches;
 }
 /** Group expiration updates by sObject and chunk them, building the Id + ExpirationDate records. */
-function updateBatches(updates) {
+function buildUpdateBatches(updates) {
     const bySobject = new Map();
     for (const update of updates) {
         const { sobject } = assignmentObjects[update.kind];
@@ -85,7 +188,7 @@ function updateBatches(updates) {
     return batches;
 }
 /** Group removals by sObject and chunk them for the Collections API. */
-function removalBatches(removals) {
+function buildRemovalBatches(removals) {
     const bySobject = new Map();
     for (const removal of removals) {
         const { sobject } = assignmentObjects[removal.kind];
@@ -101,6 +204,13 @@ function removalBatches(removals) {
     }
     return batches;
 }
+/** Classify a membership row: a group grant when it carries a group id, otherwise a plain permission set. */
+function classifyMembership(record) {
+    if (record.PermissionSetGroupId && record.PermissionSetGroup) {
+        return { kind: 'permissionSetGroup', target: record.PermissionSetGroup.DeveloperName };
+    }
+    return { kind: 'permissionSet', target: record.PermissionSet.Name };
+}
 /** Adapter backing OrgClient with a Salesforce Connection. autoFetchQuery pages past 2000 rows. */
 export class ConnectionOrgClient {
     connection;
@@ -108,13 +218,20 @@ export class ConnectionOrgClient {
         this.connection = connection;
     }
     async findUsers(usernames) {
-        const records = await this.query(`SELECT Id, Username, IsActive FROM User WHERE Username IN (${inList(usernames)})`);
+        const records = await this.query(buildUserQuery(usernames));
         return records.map((record) => ({ id: record.Id, username: record.Username, isActive: record.IsActive }));
     }
-    async findTargets(kind, names) {
-        const { sobject, field } = targetObjects[kind];
-        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 findPermissionSets(names) {
+        const records = await this.query(buildPermissionSetQuery(names));
+        return records.map((record) => ({ id: record.Id, name: record.Name }));
+    }
+    async findPermissionSetGroups(names) {
+        const records = await this.query(buildPermissionSetGroupQuery(names));
+        return records.map((record) => ({ id: record.Id, name: record.DeveloperName }));
+    }
+    async findPermissionSetLicenses(names) {
+        const records = await this.query(buildPermissionSetLicenseQuery(names));
+        return records.map((record) => ({ id: record.Id, name: record.DeveloperName }));
     }
     async listAssignments(filter) {
         const kinds = filter?.kinds;
@@ -132,141 +249,106 @@ export class ConnectionOrgClient {
         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 soql = buildMembershipQuery(usernames, wantsPermissionSet, wantsGroup);
         const records = await this.query(soql);
         return records.map((record) => {
-            const expiration = record.ExpirationDate ? { expiration: record.ExpirationDate } : {};
-            return record.PermissionSetGroupId && record.PermissionSetGroup
-                ? {
-                    assignee: record.Assignee.Username,
-                    kind: 'permissionSetGroup',
-                    target: record.PermissionSetGroup.DeveloperName,
-                    ...expiration,
-                }
-                : {
-                    assignee: record.Assignee.Username,
-                    kind: 'permissionSet',
-                    target: record.PermissionSet.Name,
-                    ...expiration,
-                };
+            const { kind, target } = classifyMembership(record);
+            return {
+                kind,
+                target,
+                assignee: record.Assignee.Username,
+                expiration: record.ExpirationDate,
+            };
         });
     }
     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 soql = buildLicenseQuery(usernames);
         const records = await this.query(soql);
         return records.map((record) => ({
             assignee: record.Assignee.Username,
             kind: 'permissionSetLicense',
             target: record.PermissionSetLicense.DeveloperName,
+            expiration: null,
         }));
     }
-    async currentAssignments(targets) {
+    async listCurrentAssignments(targets) {
         const permissionSetIds = targets.filter((ref) => ref.kind === 'permissionSet').map((ref) => ref.id);
         const groupIds = targets.filter((ref) => ref.kind === 'permissionSetGroup').map((ref) => ref.id);
         const licenseIds = targets.filter((ref) => ref.kind === 'permissionSetLicense').map((ref) => ref.id);
         const tasks = [];
-        const memberClauses = [];
-        if (permissionSetIds.length > 0)
-            memberClauses.push(`PermissionSetId IN (${inList(permissionSetIds)})`);
-        if (groupIds.length > 0)
-            memberClauses.push(`PermissionSetGroupId IN (${inList(groupIds)})`);
-        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.membershipAssignments(soql));
+        if (permissionSetIds.length > 0 || groupIds.length > 0) {
+            const soql = buildCurrentMembershipQuery(permissionSetIds, groupIds);
+            tasks.push(this.listMembershipAssignments(soql));
         }
         if (licenseIds.length > 0) {
-            const soql = 'SELECT Id, Assignee.Username, PermissionSetLicense.DeveloperName ' +
-                `FROM PermissionSetLicenseAssign WHERE PermissionSetLicenseId IN (${inList(licenseIds)})`;
-            tasks.push(this.licenseAssignments(soql));
+            const soql = buildCurrentLicenseQuery(licenseIds);
+            tasks.push(this.listLicenseAssignments(soql));
         }
         const results = await Promise.all(tasks);
         return results.flat();
     }
-    async membershipAssignments(soql) {
+    async listMembershipAssignments(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,
-                };
+            const { kind, target } = classifyMembership(record);
+            return {
+                kind,
+                target,
+                recordId: record.Id,
+                assignee: record.Assignee.Username,
+                expiration: record.ExpirationDate,
+            };
         });
     }
-    async licenseAssignments(soql) {
+    async listLicenseAssignments(soql) {
         const records = await this.query(soql);
         return records.map((record) => ({
             recordId: record.Id,
             assignee: record.Assignee.Username,
             kind: 'permissionSetLicense',
             target: record.PermissionSetLicense.DeveloperName,
+            expiration: null,
         }));
     }
     async addAssignments(additions) {
-        const batches = additionBatches(additions);
+        const batches = buildAdditionBatches(additions);
         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 };
+            return { batch, results };
         }));
         const outcomes = [];
         for (const { batch, results } of settled) {
             batch.additions.forEach((addition, index) => {
-                outcomes.push(outcomeOf(addition, 'add', results[index]));
+                outcomes.push(deriveOutcome(addition, 'add', results[index]));
             });
         }
         return outcomes;
     }
     async updateAssignments(updates) {
-        const batches = updateBatches(updates);
+        const batches = buildUpdateBatches(updates);
         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 };
+            return { batch, results };
         }));
         const outcomes = [];
         for (const { batch, results } of settled) {
             batch.updates.forEach((update, index) => {
-                outcomes.push(outcomeOf(update, 'update', results[index]));
+                outcomes.push(deriveOutcome(update, 'update', results[index]));
             });
         }
         return outcomes;
     }
     async removeAssignments(removals) {
-        const batches = removalBatches(removals);
+        const batches = buildRemovalBatches(removals);
         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 };
+            return { batch, results };
         }));
         const outcomes = [];
         for (const { batch, results } of settled) {
             batch.removals.forEach((removal, index) => {
-                outcomes.push(outcomeOf(removal, 'remove', results[index]));
+                outcomes.push(deriveOutcome(removal, 'remove', results[index]));
             });
         }
         return outcomes;