sf-plugin-permission-sets 0.0.0-dev → 0.0.0-dev.11

package/README.md

@@ -16,16 +16,17 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Quick start](#quick-start)
 - [Permission files](#permission-files)
 - [Organizing files](#organizing-files)
+- [Validations](#validations)
 - [Modes](#modes)
 - [Commands](#commands)
-- [CI/CD](#cicd)
 - [Inspiration & equivalents](#inspiration--equivalents)
+- [Versioning](#versioning)
 
 ---
 
 ## 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 +35,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
 
@@ -153,6 +156,18 @@ sf ps apply -o qa   --file "permissions/qa/*.yml"
 
 The two compose: a directory per environment, each split into functional files.
 
+## 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 username key appears twice in one file | `check` (offline) | ❌ error | Rejected, the intent is ambiguous |
+| Same target listed twice for a user, like `[Sales_Manager, Sales_Manager]` | `check` (offline) | ⚠️ warning | Deduped |
+| A user with no scopes, or an empty list | `check` (offline) | ⚠️ warning | Ignored as a no-op |
+| Same user in two files with different targets | `check` (offline) | ✅ ok | Merged into one model, the point of slicing |
+| Declared user, permission set, group, or license missing or not unique | `validate` (online) | ❌ error | Run fails before any change |
+
 ## 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`):
@@ -188,11 +203,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`
@@ -277,69 +292,48 @@ FLAGS
   --permission-sets=<names>  Comma-separated list to export (default: all assignable).
 ```
 
-## CI/CD
+## Inspiration & equivalents
+
+This plugin's command surface borrows ideas from tools you already know:
 
-A typical ladder: lint on every PR, plan against a sandbox, apply on merge:
+- [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)
 
-```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
-```
+## Versioning
 
-> **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.
+Releases follow [semantic versioning](https://semver.org). Snapshots are automatic, real releases are a manual decision.
 
-## Inspiration & equivalents
+**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.
+
+| 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"
+```
 
-The command surface borrows deliberately from tools you already know:
+| 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` |
 
-| 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                          |
+The `next` tag is selected whenever the version contains a hyphen, not by GitHub's prerelease checkbox.
 
 ## License
 

package/lib/commands/ps/info.d.ts

@@ -0,0 +1,11 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+export type PsInfoResult = {
+    name: string;
+    description: string;
+};
+export default class Info extends SfCommand<PsInfoResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    run(): Promise<PsInfoResult>;
+}

package/lib/commands/ps/info.js

@@ -0,0 +1,17 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('sf-plugin-permission-sets', 'ps.info');
+export default class Info extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    async run() {
+        await this.parse(Info);
+        const name = 'sf-plugin-permission-sets';
+        const description = 'Declarative, GitOps-style management of permission set assignments.';
+        this.log(messages.getMessage('info.summary', [name, description]));
+        return { name, description };
+    }
+}
+//# sourceMappingURL=info.js.map

package/lib/commands/ps/info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../../../src/commands/ps/info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAC;AAO/E,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,SAAuB;IAChD,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAE5D,KAAK,CAAC,GAAG;QACd,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,2BAA2B,CAAC;QACzC,MAAM,WAAW,GAAG,qEAAqE,CAAC;QAC1F,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: {};
+export default _default;

package/lib/index.js

@@ -0,0 +1,2 @@
+export default {};
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAe,EAAE,CAAC"}

package/messages/ps.info.md

@@ -0,0 +1,17 @@
+# summary
+
+Show information about the permission-sets plugin.
+
+# description
+
+Print the plugin name and what it does. A quick way to confirm the plugin is installed and working.
+
+# examples
+
+- Show plugin info:
+
+  <%= config.bin %> <%= command.id %>
+
+# info.summary
+
+%s - %s