sf-plugin-permission-sets 0.0.0-dev.9 → 0.2.0

package/oclif.manifest.json

@@ -1,11 +1,13 @@
 {
   "commands": {
-    "ps:info": {
+    "ps:apply": {
       "aliases": [],
       "args": {},
-      "description": "Print the plugin name and what it does. A quick way to confirm the plugin is installed and working.",
+      "description": "Load the files, resolve every user and target against the org, diff the desired state against what the org currently has, then add, update expirations, and/or remove assignments per the mode. Additions, expiration updates, and removals run through the sObject Collections API with partial success, so one bad record does not roll back the rest. Deletions are capped by --max-deletes and confirmed before they run. Run validate and a --dry-run first.",
       "examples": [
-        "Show plugin info:\n<%= config.bin %> <%= command.id %>"
+        "Preview a full reconcile of the dev org without changing anything:\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\" --target-org dev --mode sync --dry-run",
+        "Grant any missing assignments (additive, the default):\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\" --target-org dev",
+        "Full reconcile of production in CI, without prompts:\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\" --target-org prod --mode sync --no-prompt"
       ],
       "flags": {
         "json": {
@@ -22,30 +24,383 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "char": "f",
+          "name": "file",
+          "required": true,
+          "summary": "YAML file or glob to apply. Repeatable.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "mode": {
+          "name": "mode",
+          "summary": "Which half of the reconcile to run: additive adds missing assignments and updates expirations, destructive removes only, sync does both.",
+          "default": "additive",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "additive",
+            "destructive",
+            "sync"
+          ],
+          "type": "option"
+        },
+        "max-deletes": {
+          "name": "max-deletes",
+          "summary": "Abort before any change if the run would remove more than this many assignments.",
+          "default": 50,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "Resolve and diff, print the plan, and change nothing.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-prompt": {
+          "name": "no-prompt",
+          "summary": "Skip the deletion confirmation prompt. Required to delete in JSON or other non-interactive runs.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "ps:apply",
+      "pluginAlias": "sf-plugin-permission-sets",
+      "pluginName": "sf-plugin-permission-sets",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Reconcile a target org to match the permission set assignment files.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "ps",
+        "apply.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "ps:apply",
+        "apply:ps"
+      ]
+    },
+    "ps:check": {
+      "aliases": [],
+      "args": {},
+      "description": "Parse and validate the YAML files offline. Reports invalid YAML, schema violations, duplicate keys, duplicate targets, and empty entries. Run it in a pre-commit hook or in CI before validate, plan, or apply.",
+      "examples": [
+        "Check every file under permissions:\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\"",
+        "Check specific files:\n<%= config.bin %> <%= command.id %> --file permissions/sales.yml --file permissions/service.yml"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "char": "f",
+          "name": "file",
+          "required": true,
+          "summary": "YAML file or glob to check. Repeatable.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "strict": {
+          "name": "strict",
+          "summary": "Treat warnings as errors.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "ps:info",
+      "id": "ps:check",
+      "pluginAlias": "sf-plugin-permission-sets",
+      "pluginName": "sf-plugin-permission-sets",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Statically check permission set assignment files, with no org connection.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "ps",
+        "check.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "ps:check",
+        "check:ps"
+      ]
+    },
+    "ps:export": {
+      "aliases": [],
+      "args": {},
+      "description": "Query the target org for every assignable permission set, group, and license assignment held by active users and write them to a single user-keyed YAML file. The result is valid input for check, validate, plan, and apply, so it is a read-only way to bootstrap adoption from an org's current state. Profile-owned permission sets and inactive users are skipped.",
+      "examples": [
+        "Export the dev org's assignments to permissions.yml:\n<%= config.bin %> <%= command.id %> --target-org dev --output-file permissions.yml",
+        "Export a production org into an environment folder:\n<%= config.bin %> <%= command.id %> --target-org prod --output-file permissions/prod.yml"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "output-file": {
+          "name": "output-file",
+          "required": true,
+          "summary": "Path of the YAML file to write. Created (and its parent directories) if missing, overwritten if present.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "ps:export",
+      "pluginAlias": "sf-plugin-permission-sets",
+      "pluginName": "sf-plugin-permission-sets",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Generate a YAML file from the current org's permission set assignments.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "ps",
+        "export.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "ps:export",
+        "export:ps"
+      ]
+    },
+    "ps:plan": {
+      "aliases": [],
+      "args": {},
+      "description": "Load the files, resolve every user and target against the org, fetch the org's current assignments, and diff the desired state against them. Read-only: it queries the org but never changes it, so it is the apply pipeline stopping before any DML. The full picture (assignments to add and would-be removes) is always shown regardless of mode, and whatever the chosen mode would not act on is surfaced as drift. Run it before apply to preview what would change.",
+      "examples": [
+        "Preview a full reconcile of the dev org:\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\" --target-org dev --mode sync",
+        "Preview only the additions the default additive run would make:\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\" --target-org dev",
+        "Preview a full reconcile of production before applying it:\n<%= config.bin %> <%= command.id %> --file \"permissions/*.yml\" --target-org prod --mode sync"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "char": "f",
+          "name": "file",
+          "required": true,
+          "summary": "YAML file or glob to plan. Repeatable.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "mode": {
+          "name": "mode",
+          "summary": "Which half of the reconcile to preview: additive adds and updates expirations, destructive removes only, sync does both. Adds, expiration updates, and removes are always shown either way.",
+          "default": "additive",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "additive",
+            "destructive",
+            "sync"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "ps:plan",
+      "pluginAlias": "sf-plugin-permission-sets",
+      "pluginName": "sf-plugin-permission-sets",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Preview the changes that would reconcile a target org to the assignment files.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "ps",
+        "plan.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "ps:plan",
+        "plan:ps"
+      ]
+    },
+    "ps:validate": {
+      "aliases": [],
+      "args": {},
+      "description": "Run every offline check, then resolve each referenced user, permission set, group, and license against the org. Reports users that are missing or inactive and targets that are missing or not unique. Read-only: it queries the org but never changes it. Run it before plan or apply.",
+      "examples": [
+        "Validate every file under permissions against the dev org:\n<%= config.bin %> <%= command.id %> --file \"permissions/\\*.yml\" --target-org dev",
+        "Validate specific files against a named org:\n<%= config.bin %> <%= command.id %> --file permissions/sales.yml --file permissions/service.yml --target-org prod"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "char": "f",
+          "name": "file",
+          "required": true,
+          "summary": "YAML file or glob to validate. Repeatable.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "ps:validate",
       "pluginAlias": "sf-plugin-permission-sets",
       "pluginName": "sf-plugin-permission-sets",
       "pluginType": "core",
       "strict": true,
-      "summary": "Show information about the permission-sets plugin.",
+      "summary": "Validate permission set assignment files against a target org.",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "ps",
-        "info.js"
+        "validate.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "ps:info",
-        "info:ps"
+        "ps:validate",
+        "validate:ps"
       ]
     }
   },
-  "version": "0.0.0-dev.9"
+  "version": "0.2.0"
 }

package/package.json

@@ -1,7 +1,6 @@
 {
     "name": "sf-plugin-permission-sets",
-    "description": "",
-    "version": "0.0.0-dev.9",
+    "description": "Declarative, GitOps-style management of permission set assignments for Salesforce orgs.",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/zaclummys/sf-plugin-permission-sets.git"
@@ -9,7 +8,10 @@
     "dependencies": {
         "@oclif/core": "^4",
         "@salesforce/core": "^8",
-        "@salesforce/sf-plugins-core": "^12"
+        "@salesforce/sf-plugins-core": "^12",
+        "globby": "^16.2.0",
+        "yaml": "^2.9.0",
+        "zod": "^4.4.3"
     },
     "devDependencies": {
         "@salesforce/dev-scripts": "^10",
@@ -17,7 +19,8 @@
         "husky": "^7.0.4",
         "oclif": "^4.14.0",
         "ts-node": "^10.9.2",
-        "typescript": "^5.4.5"
+        "typescript": "^5.4.5",
+        "vitest": "^4.1.9"
     },
     "engines": {
         "node": ">=18.0.0"
@@ -29,13 +32,16 @@
         "/oclif.lock"
     ],
     "keywords": [
-        "force",
         "salesforce",
-        "salesforcedx",
-        "sf",
         "sf-plugin",
-        "sfdx",
-        "sfdx-plugin"
+        "sfdx-plugin",
+        "permission-sets",
+        "permission-set-assignment",
+        "permission-set-group",
+        "access-management",
+        "user-provisioning",
+        "gitops",
+        "declarative"
     ],
     "license": "BSD-3-Clause",
     "oclif": {
@@ -91,59 +97,44 @@
             "clean": "if-file-deleted"
         },
         "format": {
-            "command": "prettier --write \"+(src|test|schemas)/**/*.+(ts|js|json)|command-snapshot.json\"",
+            "command": "prettier --write \"src/**/*.+(ts|js|json)\"",
             "files": [
                 "src/**/*.ts",
-                "test/**/*.ts",
-                "schemas/**/*.json",
-                "command-snapshot.json",
                 ".prettier*"
             ],
             "output": []
         },
         "lint": {
-            "command": "eslint src test --color --cache --cache-location .eslintcache",
+            "command": "eslint src --color --cache --cache-location .eslintcache",
             "files": [
                 "src/**/*.ts",
-                "test/**/*.ts",
                 "messages/**",
                 "**/.eslint*",
                 "**/tsconfig.json"
             ],
             "output": []
         },
-        "test:compile": {
-            "command": "tsc -p \"./test\" --pretty",
-            "files": [
-                "test/**/*.ts",
-                "**/tsconfig.json"
-            ],
-            "output": []
-        },
         "test": {
             "dependencies": [
-                "test:compile",
                 "test:only",
                 "lint"
             ]
         },
         "test:only": {
-            "command": "nyc mocha \"test/**/*.test.ts\"",
+            "command": "vitest run",
             "env": {
                 "FORCE_COLOR": "2"
             },
             "files": [
-                "test/**/*.ts",
                 "src/**/*.ts",
-                "**/tsconfig.json",
-                ".mocha*",
-                "!*.nut.ts",
-                ".nycrc"
+                "vitest.config.ts",
+                "**/tsconfig.json"
             ],
             "output": []
         }
     },
     "exports": "./lib/index.js",
     "type": "module",
-    "author": "Isaac Ferreira"
+    "author": "Isaac Ferreira",
+    "version": "0.2.0"
 }

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

@@ -1,11 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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/messages/ps.info.md

@@ -1,17 +0,0 @@
-# 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