sf-plugin-permission-sets 0.0.0-dev.4 → 0.0.0-dev.42

package/README.md

@@ -1,10 +1,12 @@
 # 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) [![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.txt)
 
 > 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.
 
+> ⚠️ **Under active development.** This plugin is `0.x`. Per [semver's major-version-zero rule](https://semver.org/#spec-item-4), anything (commands, flags, the YAML schema) may change in a breaking way between `0.x` releases. Pin a version in CI. The public API stabilizes at `v1.0.0`.
+
 Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let CI show the diff, and merge to apply. Your git history becomes the audit log of who-had-access-when.
 
 ---
@@ -17,15 +19,17 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Permission files](#permission-files)
 - [Organizing files](#organizing-files)
 - [Modes](#modes)
+- [Validations](#validations)
 - [Commands](#commands)
-- [CI/CD](#cicd)
 - [Inspiration & equivalents](#inspiration--equivalents)
+- [Versioning](#versioning)
+- [Architecture](#architecture)
 
 ---
 
 ## Why
 
-Permission set assignments drift. People get access for a project and keep it forever. Offboarding misses a set. Nobody can answer "who can see X and why?" without a SOQL spelunking session.
+Permission set assignments drift. People get access for a project and keep it forever. Offboarding misses a set. Nobody can answer "who can see X and why?" without a SOQL spelunking session. And in higher environments those grants happen by hand in Setup, with no review and no trail.
 
 This plugin makes the desired state **declarative and reviewable**:
 
@@ -34,6 +38,8 @@ This plugin makes the desired state **declarative and reviewable**:
 - ✅ **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.
 - ✅ **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.
 
 ## Install
 
@@ -53,7 +59,7 @@ Requires Salesforce CLI (`sf`) and Node.js 18+.
 
 ```bash
 # 1. Bootstrap YAML from an existing org (so you don't start from scratch)
-sf ps export --target-org dev --output-dir permissions
+sf ps export --target-org dev --output-file permissions.yml
 
 # 2. Edit the files, commit, open a PR. Validate offline, no org needed:
 sf ps check --file "./permissions/*.yml"
@@ -108,6 +114,24 @@ users:
       - Sales_Manager
 ```
 
+### Timed access (expiration)
+
+A permission set or permission set group entry can be a plain name or an object with an `expiration`. The expiration is an ISO 8601 datetime, and Salesforce removes access automatically when it passes. Plain names never expire.
+
+```yaml
+users:
+  contractor@acme.com:
+    permissionSets:
+      - Read_Only                              # permanent
+      - name: Sales_Manager                    # expires automatically
+        expiration: 2026-12-31T23:59:59Z
+    permissionSetGroups:
+      - name: Project_Phoenix_Bundle
+        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, 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:
 
 ```bash
@@ -155,15 +179,27 @@ The two compose: a directory per environment, each split into functional files.
 
 ## Modes
 
-A run performs two atomic operations: **add** missing assignments and **remove** undeclared ones. The mode selects which it actually executes. Set it with `--mode` (default `additive`):
+A run performs three operations: **add** missing assignments, **update** changed expirations on declared ones, and **remove** undeclared ones. Updates ride with the additive half (they touch a declared grant, never revoke access). The mode selects which it actually executes. Set it with `--mode` (default `additive`):
+
+| Mode          | Adds missing | Updates expirations | Removes undeclared | Use when…                                                              |
+| ------------- | :----------: | :-----------------: | :----------------: | --------------------------------------------------------------------- |
+| `sync`        | ✅           | ✅                  | ✅                 | Full reconcile: make the org exactly match the YAML (`sync` = `additive` + `destructive`). |
+| `additive`    | ✅           | ✅                  | ❌                 | **Default.** Grant access, never revoke. Safe rollout.                |
+| `destructive` | ❌           | ❌                  | ✅                 | Prune/revoke access that isn't declared, without granting anything new. |
 
-| Mode          | Adds missing | Removes undeclared | Use when…                                                              |
-| ------------- | :----------: | :----------------: | --------------------------------------------------------------------- |
-| `additive`    | ✅           | ❌                 | **Default.** Grant access, never revoke. Safe rollout.                |
-| `destructive` | ❌           | ✅                 | Prune/revoke access that isn't declared, without granting anything new. |
-| `sync`        | ✅           | ✅                 | Full reconcile: make the org exactly match the YAML (`sync` = `additive` + `destructive`). |
+`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.
 
-`plan` always shows the *full* picture (both adds **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**. Gate CI on it with `--fail-on-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.
+
+| 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 |
 
 ## Commands
 
@@ -171,7 +207,7 @@ A run performs two atomic operations: **add** missing assignments and **remove**
 | ---------------- | ---------------------------------------------------------------------- |
 | `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. Optionally fail on drift. |
+| `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.        |
 
@@ -188,11 +224,11 @@ FLAGS
   --strict                 Treat warnings as errors.
 
 CHECKS
-  • valid YAML & schema (unknown keys rejected)
-  • duplicate assignees / duplicate (user, target) pairs
-  • conflicting intent across files
-  • empty or malformed assignee usernames
-  • internal referential integrity
+  - valid YAML & schema (unknown keys rejected)
+  - duplicate assignees / duplicate (user, target) pairs
+  - conflicting intent across files
+  - empty or malformed assignee usernames
+  - internal referential integrity
 ```
 
 ### `sf ps validate`
@@ -213,36 +249,57 @@ group, and license referenced actually exists and resolves uniquely.
 
 ```
 USAGE
-  $ sf ps plan -o <org> -f <glob>... [--mode <value>] [--fail-on-drift] [--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]
-  --fail-on-drift          Exit non-zero if any change is pending (for CI gates).
+  --show-unchanged         List assignments that already match, instead of only counting them.
 ```
 
-Example output:
+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
-    - 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 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`
@@ -250,7 +307,7 @@ Plan: 2 to add, 1 to remove, 1 unchanged.
 ```
 USAGE
   $ sf ps apply -o <org> -f <glob>... [--mode <value>] [--max-deletes <n>]
-                [--dry-run] [--no-prompt] [--json]
+                [--dry-run] [--show-unchanged] [--no-prompt] [--json]
 
 FLAGS
   -o, --target-org=<org>   (required)
@@ -258,6 +315,7 @@ FLAGS
   --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).
 ```
 
@@ -265,81 +323,87 @@ Deletions always prompt for confirmation unless `--no-prompt` is set, and are ha
 
 ### `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.
+
 ```
 USAGE
-  $ sf ps export -o <org> [--output-dir <dir>] [--layout <value>]
-                      [--permission-sets <names>] [--json]
+  $ sf ps export -o <org> --output-file <file> [--json]
 
 FLAGS
-  -o, --target-org=<org>     (required)
-  --output-dir=<dir>         [default: permissions] Where to write the generated YAML.
-  --layout=<value>           by-permission-set | by-user   [default: by-permission-set]
-  --permission-sets=<names>  Comma-separated list to export (default: all assignable).
+  -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.
 ```
 
-## CI/CD
+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.
 
-A typical ladder: lint on every PR, plan against a sandbox, apply on merge:
+## Inspiration & equivalents
 
-```yaml
-# .github/workflows/ps-gitops.yml
-name: ps-gitops
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm install -g @salesforce/cli
-      - run: sf plugins install sf-plugin-permission-sets
-      - run: sf ps check --file "permissions/*.yml" --strict
-
-  plan:
-    if: github.event_name == 'pull_request'
-    needs: check
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm install -g @salesforce/cli
-      - run: sf plugins install sf-plugin-permission-sets
-      # Auth via Sfdx auth URL stored in a secrets manager, never hardcode credentials
-      - run: echo "$SF_AUTH_URL" | sf org login sfdx-url --sfdx-url-stdin --alias target
-        env:
-          SF_AUTH_URL: ${{ secrets.SF_AUTH_URL }}
-      - run: sf ps plan -o target --file "permissions/*.yml" --mode sync --fail-on-drift
-
-  apply:
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    needs: check
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm install -g @salesforce/cli
-      - run: sf plugins install sf-plugin-permission-sets
-      - run: echo "$SF_AUTH_URL" | sf org login sfdx-url --sfdx-url-stdin --alias target
-        env:
-          SF_AUTH_URL: ${{ secrets.SF_AUTH_URL }}
-      - run: sf ps apply -o target --file "permissions/*.yml" --mode sync --no-prompt --max-deletes 25
-```
+This plugin's command surface borrows ideas from tools you already know:
 
-> **Credentials:** the plugin never reads or stores secrets itself. It uses orgs you've already authenticated with `sf`. In CI, inject auth from your platform's secrets store (as above), not from committed files.
+- [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)
 
-## Inspiration & equivalents
+## Versioning
 
-The command surface borrows deliberately from tools you already know:
+Releases follow [semantic versioning](https://semver.org). Snapshots are automatic, real releases are a manual decision.
+
+**Automatic, no action needed:**
+
+- Every push to `main` publishes a snapshot `0.0.0-dev.<run>` to the `dev` dist-tag.
+- Creating a release triggers CI to build, stamp the version from the tag, publish it with provenance, and smoke-test the result.
+
+**Manual, you decide and trigger:**
+
+- Choosing the version bump (patch, minor, or major).
+- Creating the GitHub Release, which is what triggers the publish above.
+
+**While on `0.x`:** breaking changes may ship in **any** release, including minor bumps. The plugin is under active development and the public API is not yet stable. The table below describes the contract that takes effect at `v1.0.0`.
+
+| Bump | When | Example tag |
+| --- | --- | --- |
+| patch | bug fix, no behavior change | `v0.1.1` |
+| minor | new backward-compatible feature | `v0.2.0` |
+| major | breaking change to a command, flag, or the YAML schema | `v1.0.0` |
+
+Cut a release with a tag off `main`:
+
+```bash
+gh release create v0.2.0 --target main --title v0.2.0 --notes "Add ps export"
+```
 
-| This plugin          | Terraform              | CloudFormation / SAM            | sf core                    |
-| -------------------- | ---------------------- | ------------------------------- | -------------------------- |
-| `ps check`      | `terraform validate`   | `sam validate --lint`           | n/a                          |
-| `ps validate`   | `terraform plan` (refresh) | `cfn validate-template`     | `project deploy validate`  |
-| `ps plan`       | `terraform plan`       | `cfn create-change-set`         | `project deploy preview`   |
-| `ps apply`      | `terraform apply`      | `cfn execute-change-set` / `sam deploy` | `project deploy start` |
-| `ps export`     | `terraform import`     | n/a                               | n/a                          |
-| `--fail-on-drift`    | drift in plan exit code | `cfn detect-stack-drift`       | n/a                          |
+| 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.
+
+- **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.
+- **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.
+
+| Core module | Responsibility |
+| --- | --- |
+| `model` | Shared domain types (assignment, org, diff). |
+| `finding` | The finding type and code vocabulary, plus constructors, formatting, and counting. |
+| `schema` | The zod contract for a file, plus validation. |
+| `parse` | File text to an object, with YAML and duplicate-key errors. |
+| `normalize` | A validated file to canonical `(assignee, kind, target)` tuples, plus structural findings. |
+| `serialize` | Canonical tuples back to a user-keyed YAML document (the inverse of `normalize`). |
+| `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. |
+| `report` | Format a diff as a plan. |
+
+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.
 
 ## License
 

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

@@ -0,0 +1,17 @@
+import { Connection } from '@salesforce/core';
+import { ActualAssignment, 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[]>;
+    currentAssignments(targets: TargetRef[]): Promise<ActualAssignment[]>;
+    addAssignments(additions: ResolvedAddition[]): Promise<AssignmentOutcome[]>;
+    updateAssignments(updates: AssignmentUpdate[]): Promise<AssignmentOutcome[]>;
+    removeAssignments(removals: ActualAssignment[]): Promise<AssignmentOutcome[]>;
+    private query;
+}
+//# sourceMappingURL=connection-org-client.d.ts.map

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

@@ -0,0 +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,+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,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"}

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

@@ -0,0 +1,248 @@
+/** 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' },
+    permissionSetGroup: { sobject: 'PermissionSetAssignment', idField: 'PermissionSetGroupId' },
+    permissionSetLicense: { sobject: 'PermissionSetLicenseAssign', idField: 'PermissionSetLicenseId' },
+};
+/** 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) {
+    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(', ');
+}
+/** Split items into chunks of at most `size`. */
+function chunk(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}
+/** Turn a per-record DML result into a domain outcome, capturing the error message on failure. */
+function outcomeOf(assignment, operation, result) {
+    const success = result?.success ?? false;
+    const message = result && !result.success ? result.errors.map((error) => error.message).join('; ') : undefined;
+    return {
+        assignee: assignment.assignee,
+        kind: assignment.kind,
+        target: assignment.target,
+        operation,
+        success,
+        message,
+    };
+}
+/** Group additions by sObject and chunk them for the Collections API, keeping each record's source. */
+function additionBatches(additions) {
+    const bySobject = new Map();
+    for (const addition of additions) {
+        const { sobject } = assignmentObjects[addition.kind];
+        const grouped = bySobject.get(sobject) ?? [];
+        grouped.push(addition);
+        bySobject.set(sobject, grouped);
+    }
+    const batches = [];
+    for (const [sobject, grouped] of bySobject) {
+        for (const batch of chunk(grouped, collectionBatchSize)) {
+            const records = batch.map((addition) => ({
+                AssigneeId: addition.assigneeId,
+                [assignmentObjects[addition.kind].idField]: addition.targetId,
+                ...(addition.expiration ? { ExpirationDate: addition.expiration } : {}),
+            }));
+            batches.push({ sobject, additions: batch, records });
+        }
+    }
+    return batches;
+}
+/** Group expiration updates by sObject and chunk them, building the Id + ExpirationDate records. */
+function updateBatches(updates) {
+    const bySobject = new Map();
+    for (const update of updates) {
+        const { sobject } = assignmentObjects[update.kind];
+        const grouped = bySobject.get(sobject) ?? [];
+        grouped.push(update);
+        bySobject.set(sobject, grouped);
+    }
+    const batches = [];
+    for (const [sobject, grouped] of bySobject) {
+        for (const batch of chunk(grouped, collectionBatchSize)) {
+            const records = batch.map((update) => ({
+                Id: update.recordId,
+                ExpirationDate: update.expiration ?? null,
+            }));
+            batches.push({ sobject, updates: batch, records });
+        }
+    }
+    return batches;
+}
+/** Group removals by sObject and chunk them for the Collections API. */
+function removalBatches(removals) {
+    const bySobject = new Map();
+    for (const removal of removals) {
+        const { sobject } = assignmentObjects[removal.kind];
+        const grouped = bySobject.get(sobject) ?? [];
+        grouped.push(removal);
+        bySobject.set(sobject, grouped);
+    }
+    const batches = [];
+    for (const [sobject, grouped] of bySobject) {
+        for (const batch of chunk(grouped, collectionBatchSize)) {
+            batches.push({ sobject, removals: batch });
+        }
+    }
+    return batches;
+}
+/** Adapter backing OrgClient with a Salesforce Connection. autoFetchQuery pages past 2000 rows. */
+export class ConnectionOrgClient {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    async findUsers(usernames) {
+        const records = await this.query(`SELECT Id, Username, IsActive FROM User WHERE Username IN (${inList(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 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) {
+            const expiration = record.ExpirationDate ? { expiration: record.ExpirationDate } : {};
+            if (record.PermissionSetGroupId && record.PermissionSetGroup) {
+                assignments.push({
+                    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 currentAssignments(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.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,
+                    };
+            })));
+        }
+        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,
+            }))));
+        }
+        const results = await Promise.all(tasks);
+        return results.flat();
+    }
+    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 outcomes = [];
+        for (const { batch, results } of settled) {
+            batch.additions.forEach((addition, index) => {
+                outcomes.push(outcomeOf(addition, 'add', results[index]));
+            });
+        }
+        return outcomes;
+    }
+    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 outcomes = [];
+        for (const { batch, results } of settled) {
+            batch.updates.forEach((update, index) => {
+                outcomes.push(outcomeOf(update, 'update', results[index]));
+            });
+        }
+        return outcomes;
+    }
+    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 outcomes = [];
+        for (const { batch, results } of settled) {
+            batch.removals.forEach((removal, index) => {
+                outcomes.push(outcomeOf(removal, 'remove', results[index]));
+            });
+        }
+        return outcomes;
+    }
+    async query(soql) {
+        const result = await this.connection.autoFetchQuery(soql);
+        return result.records;
+    }
+}
+//# sourceMappingURL=connection-org-client.js.map