sf-plugin-permission-sets 0.0.0-dev.10 → 0.0.0-dev.12

package/README.md

@@ -19,7 +19,6 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Validations](#validations)
 - [Modes](#modes)
 - [Commands](#commands)
-- [CI/CD](#cicd)
 - [Inspiration & equivalents](#inspiration--equivalents)
 - [Versioning](#versioning)
 
@@ -27,7 +26,7 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 
 ## 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**:
 
@@ -36,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
 
@@ -195,29 +196,33 @@ Fully offline: runs in any CI job or pre-commit hook without org credentials.
 
 ```
 USAGE
-  $ sf ps check -f <glob>... [--strict] [--json]
+  $ sf ps check -f <glob>... [--strict] [--watch] [--json]
 
 FLAGS
   -f, --file=<glob>...     (required) YAML file(s) to read. Repeatable, globs are expanded by the plugin.
   --strict                 Treat warnings as errors.
+  -w, --watch              Re-run on every change to a matched file. Stays in the foreground until you stop it (Ctrl-C).
 
 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
 ```
 
+`--watch` is for the local edit loop: leave it running while you tweak the YAML and the findings refresh on every save. It re-expands the globs each run, so files you add or delete are picked up too. It's a foreground, interactive mode, so it can't be combined with `--json` and isn't meant for CI, where a single gated `check` run is what you want.
+
 ### `sf ps validate`
 
 ```
 USAGE
-  $ sf ps validate -o <org> -f <glob>... [--json]
+  $ sf ps validate -o <org> -f <glob>... [--watch] [--json]
 
 FLAGS
   -o, --target-org=<org>   (required) Org to resolve against.
   -f, --file=<glob>...     (required) YAML file(s) to read. Repeatable, globs expanded by the plugin.
+  -w, --watch              Re-run on every change to a matched file. Read-only, but each run queries the org, so point it at a scratch or dev org.
 
 Runs all offline checks, then verifies that every user (active), permission set,
 group, and license referenced actually exists and resolves uniquely.
@@ -227,13 +232,14 @@ 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>] [--fail-on-drift] [--watch] [--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).
+  -w, --watch              Re-diff against the org on every change to a matched file. Read-only (never applies), but each run queries the org.
 ```
 
 Example output:
@@ -291,73 +297,28 @@ FLAGS
   --permission-sets=<names>  Comma-separated list to export (default: all assignable).
 ```
 
-## CI/CD
+## Inspiration & equivalents
 
-A typical ladder: lint on every PR, plan against a sandbox, apply on merge:
+This plugin's command surface borrows ideas from tools you already know:
 
-```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
-```
+- [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)
 
-> **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.
+## Versioning
 
-## Inspiration & equivalents
+Releases follow [semantic versioning](https://semver.org). Snapshots are automatic, real releases are a manual decision.
 
-The command surface borrows deliberately from tools you already know:
+**Automatic, no action needed:**
 
-| 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                          |
+- 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.
 
-## Versioning
+**Manual, you decide and trigger:**
 
-Releases follow [semantic versioning](https://semver.org). You choose the bump by the git tag you create, and CI stamps and routes it to the right npm dist-tag.
+- Choosing the version bump (patch, minor, or major).
+- Creating the GitHub Release, which is what triggers the publish above.
 
 | Bump | When | Example tag |
 | --- | --- | --- |
@@ -365,19 +326,19 @@ Releases follow [semantic versioning](https://semver.org). You choose the bump b
 | minor | new backward-compatible feature | `v0.2.0` |
 | major | breaking change to a command, flag, or the YAML schema | `v1.0.0` |
 
-| dist-tag | Source | Install |
-| --- | --- | --- |
-| `latest` | a GitHub Release with a normal tag like `v1.2.0` | `sf plugins install sf-plugin-permission-sets` |
-| `next` | a Release whose tag has a hyphen, like `v1.3.0-beta.1` | `sf plugins install sf-plugin-permission-sets@next` |
-| `dev` | every push to `main`, published as `0.0.0-dev.<run>` | `sf plugins install sf-plugin-permission-sets@dev` |
-
 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 `next` tag is selected whenever the version contains a hyphen, not by GitHub's prerelease checkbox. The `dev` snapshots publish automatically on every push to `main`, so they need no command.
+| 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.
 
 ## License
 

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

@@ -0,0 +1,18 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { Finding } from '../../core/model.js';
+export type PsCheckResult = {
+    files: number;
+    users: number;
+    assignments: number;
+    findings: Finding[];
+};
+export default class Check extends SfCommand<PsCheckResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly flags: {
+        file: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        strict: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<PsCheckResult>;
+}

package/lib/commands/ps/check.js

@@ -0,0 +1,45 @@
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { CheckService } from '../../services/check.js';
+import { formatFindings } from '../../core/report.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('sf-plugin-permission-sets', 'ps.check');
+export default class Check extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static flags = {
+        file: Flags.string({
+            char: 'f',
+            summary: messages.getMessage('flags.file.summary'),
+            required: true,
+            multiple: true,
+        }),
+        strict: Flags.boolean({
+            summary: messages.getMessage('flags.strict.summary'),
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Check);
+        const result = await new CheckService().run({ files: flags.file, strict: flags.strict });
+        for (const line of formatFindings(result.findings)) {
+            this.log(line);
+        }
+        const users = new Set(result.assignments.map((a) => a.assignee)).size;
+        this.log('');
+        this.log(messages.getMessage('summary.counts', [String(result.errors), String(result.warnings)]));
+        if (result.failed) {
+            process.exitCode = 1;
+            if (!this.jsonEnabled()) {
+                this.error(messages.getMessage('error.failed'), { exit: 1 });
+            }
+        }
+        return {
+            files: result.files.length,
+            users,
+            assignments: result.assignments.length,
+            findings: result.findings,
+        };
+    }
+}
+//# sourceMappingURL=check.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../../src/commands/ps/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,2BAA2B,EAAE,UAAU,CAAC,CAAC;AAShF,MAAM,CAAC,OAAO,OAAO,KAAM,SAAQ,SAAwB;IAClD,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,MAAM,CAAU,KAAK,GAAG;QAC7B,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;YACjB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,oBAAoB,CAAC;YAClD,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,IAAI;SACf,CAAC;QACF,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC;YACpB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC;SACrD,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,YAAY,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAEzF,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;QACtE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAElG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QAED,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;YAC1B,KAAK;YACL,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM;YACtC,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAC;IACJ,CAAC"}

package/lib/core/load.d.ts

@@ -0,0 +1,8 @@
+import { DesiredAssignment, Finding, LoadResult } from './model.js';
+/** Process one file's text through parse, validate, and normalize. Pure, no disk. */
+export declare function checkContent(text: string, file: string): {
+    assignments: DesiredAssignment[];
+    findings: Finding[];
+};
+/** Expand the globs, read every matched file, and merge into one model by union. */
+export declare function loadFiles(patterns: string[]): Promise<LoadResult>;

package/lib/core/load.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { globby } from 'globby';
+import { parseFile } from './parse.js';
+import { validateFile } from './schema.js';
+import { normalize } from './normalize.js';
+/** Process one file's text through parse, validate, and normalize. Pure, no disk. */
+export function checkContent(text, file) {
+    const parsed = parseFile(text, file);
+    if (!parsed.data) {
+        return { assignments: [], findings: parsed.findings };
+    }
+    const validated = validateFile(parsed.data, file);
+    if (!validated.data) {
+        return { assignments: [], findings: [...parsed.findings, ...validated.findings] };
+    }
+    const normalized = normalize(validated.data, file);
+    return {
+        assignments: normalized.assignments,
+        findings: [...parsed.findings, ...validated.findings, ...normalized.findings],
+    };
+}
+/** Expand the globs, read every matched file, and merge into one model by union. */
+export async function loadFiles(patterns) {
+    const files = await globby(patterns);
+    if (files.length === 0) {
+        return {
+            files,
+            assignments: [],
+            findings: [{ level: 'error', code: 'NO_FILES', message: `no files matched: ${patterns.join(', ')}` }],
+        };
+    }
+    const findings = [];
+    const collected = [];
+    for (const file of files) {
+        // eslint-disable-next-line no-await-in-loop
+        const text = await readFile(file, 'utf8');
+        const res = checkContent(text, file);
+        findings.push(...res.findings);
+        collected.push(...res.assignments);
+    }
+    const seen = new Set();
+    const assignments = [];
+    for (const a of collected) {
+        const dedupeKey = `${a.assignee} ${a.kind} ${a.target}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        assignments.push(a);
+    }
+    return { files, assignments, findings };
+}
+//# sourceMappingURL=load.js.map

package/lib/core/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/core/load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY;IACrD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACpB,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpF,CAAC;IAED,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO;QACL,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAkB;IAChD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,KAAK;YACL,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;SACtG,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAwB,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,4CAA4C;QAC5C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrC,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC/B,SAAS,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,WAAW,GAAwB,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACxD,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC"}

package/lib/core/model.d.ts

@@ -0,0 +1,19 @@
+export type Kind = 'permissionSet' | 'permissionSetGroup' | 'permissionSetLicense';
+export type DesiredAssignment = {
+    assignee: string;
+    kind: Kind;
+    target: string;
+};
+export type FindingLevel = 'error' | 'warning';
+export type Finding = {
+    level: FindingLevel;
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+};
+export type LoadResult = {
+    files: string[];
+    assignments: DesiredAssignment[];
+    findings: Finding[];
+};

package/lib/core/model.js

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

package/lib/core/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/core/model.ts"],"names":[],"mappings":""}

package/lib/core/normalize.d.ts

@@ -0,0 +1,10 @@
+import { FileShape } from './schema.js';
+import { DesiredAssignment, Finding } from './model.js';
+/**
+ * Turn a validated file into canonical (assignee, kind, target) tuples, and
+ * emit the structural findings: duplicate targets, empty lists, empty users.
+ */
+export declare function normalize(data: FileShape, file: string): {
+    assignments: DesiredAssignment[];
+    findings: Finding[];
+};

package/lib/core/normalize.js

@@ -0,0 +1,45 @@
+const KIND_KEYS = [
+    ['permissionSet', 'permissionSets'],
+    ['permissionSetGroup', 'permissionSetGroups'],
+    ['permissionSetLicense', 'permissionSetLicenses'],
+];
+/**
+ * Turn a validated file into canonical (assignee, kind, target) tuples, and
+ * emit the structural findings: duplicate targets, empty lists, empty users.
+ */
+export function normalize(data, file) {
+    const assignments = [];
+    const findings = [];
+    for (const [username, entry] of Object.entries(data.users)) {
+        let scopeCount = 0;
+        for (const [kind, key] of KIND_KEYS) {
+            const list = entry[key];
+            if (list === undefined)
+                continue;
+            if (list.length === 0) {
+                findings.push({ level: 'warning', code: 'EMPTY_LIST', message: `${username}: ${key} is empty`, file });
+                continue;
+            }
+            scopeCount += 1;
+            const seen = new Set();
+            for (const target of list) {
+                if (seen.has(target)) {
+                    findings.push({
+                        level: 'warning',
+                        code: 'DUP_TARGET',
+                        message: `${username}: ${target} is listed twice under ${key}`,
+                        file,
+                    });
+                    continue;
+                }
+                seen.add(target);
+                assignments.push({ assignee: username, kind, target });
+            }
+        }
+        if (scopeCount === 0) {
+            findings.push({ level: 'warning', code: 'EMPTY_USER', message: `${username}: no scopes declared`, file });
+        }
+    }
+    return { assignments, findings };
+}
+//# sourceMappingURL=normalize.js.map

package/lib/core/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/core/normalize.ts"],"names":[],"mappings":"AAKA,MAAM,SAAS,GAA4B;IACzC,CAAC,eAAe,EAAE,gBAAgB,CAAC;IACnC,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;IAC7C,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;CAClD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,IAAY;IACrD,MAAM,WAAW,GAAwB,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,IAAI,KAAK,SAAS;gBAAE,SAAS;YACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,QAAQ,KAAK,GAAG,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvG,SAAS;YACX,CAAC;YAED,UAAU,IAAI,CAAC,CAAC;YAChB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,KAAK,MAAM,MAAM,IAAI,IAAI,EAAE,CAAC;gBAC1B,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACrB,QAAQ,CAAC,IAAI,CAAC;wBACZ,KAAK,EAAE,SAAS;wBAChB,IAAI,EAAE,YAAY;wBAClB,OAAO,EAAE,GAAG,QAAQ,KAAK,MAAM,0BAA0B,GAAG,EAAE;wBAC9D,IAAI;qBACL,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QAED,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,QAAQ,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5G,CAAC;IACH,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACnC,CAAC"}

package/lib/core/parse.d.ts

@@ -0,0 +1,9 @@
+import { Finding } from './model.js';
+/**
+ * Read one file's text into a plain object. Reports invalid YAML and duplicate
+ * keys (uniqueKeys), and treats an empty document as a warning.
+ */
+export declare function parseFile(text: string, file: string): {
+    data?: unknown;
+    findings: Finding[];
+};

package/lib/core/parse.js

@@ -0,0 +1,25 @@
+import { parseDocument } from 'yaml';
+/**
+ * Read one file's text into a plain object. Reports invalid YAML and duplicate
+ * keys (uniqueKeys), and treats an empty document as a warning.
+ */
+export function parseFile(text, file) {
+    const doc = parseDocument(text, { uniqueKeys: true });
+    if (doc.errors.length > 0) {
+        return {
+            findings: doc.errors.map((err) => ({
+                level: 'error',
+                code: 'YAML',
+                message: err.message,
+                file,
+                line: err.linePos?.[0]?.line,
+            })),
+        };
+    }
+    const data = doc.toJS();
+    if (data === null || data === undefined) {
+        return { findings: [{ level: 'warning', code: 'EMPTY_FILE', message: 'file is empty', file }] };
+    }
+    return { data, findings: [] };
+}
+//# sourceMappingURL=parse.js.map

package/lib/core/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/core/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAGrC;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtD,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACjC,KAAK,EAAE,OAAO;gBACd,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,IAAI;gBACJ,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;aAC7B,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAa,CAAC;IACnC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAClG,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAChC,CAAC"}

package/lib/core/report.d.ts

@@ -0,0 +1,8 @@
+import { Finding } from './model.js';
+/** Render findings as human-readable lines. Shared by check, validate, and plan. */
+export declare function formatFindings(findings: Finding[]): string[];
+/** Count findings by level. */
+export declare function countFindings(findings: Finding[]): {
+    errors: number;
+    warnings: number;
+};

package/lib/core/report.js

@@ -0,0 +1,15 @@
+/** Render findings as human-readable lines. Shared by check, validate, and plan. */
+export function formatFindings(findings) {
+    return findings.map((finding) => {
+        const where = finding.file ? `${finding.file}${finding.line ? `:${finding.line}` : ''} ` : '';
+        return `${finding.level}: ${where}${finding.message}`;
+    });
+}
+/** Count findings by level. */
+export function countFindings(findings) {
+    return {
+        errors: findings.filter((f) => f.level === 'error').length,
+        warnings: findings.filter((f) => f.level === 'warning').length,
+    };
+}
+//# sourceMappingURL=report.js.map

package/lib/core/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/core/report.ts"],"names":[],"mappings":"AAEA,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,QAAmB;IAChD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9F,OAAO,GAAG,OAAO,CAAC,KAAK,KAAK,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,aAAa,CAAC,QAAmB;IAC/C,OAAO;QACL,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,MAAM;QAC1D,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,MAAM;KAC/D,CAAC;AACJ,CAAC"}

package/lib/core/schema.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { Finding } from './model.js';
+export declare const userEntrySchema: z.ZodObject<{
+    permissionSets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    permissionSetGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    permissionSetLicenses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const fileSchema: z.ZodObject<{
+    users: z.ZodRecord<z.ZodString, z.ZodObject<{
+        permissionSets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        permissionSetGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        permissionSetLicenses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type FileShape = z.infer<typeof fileSchema>;
+/** Validate a parsed object against the file contract, turning issues into findings. */
+export declare function validateFile(data: unknown, file: string): {
+    data?: FileShape;
+    findings: Finding[];
+};

package/lib/core/schema.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+const scopeList = z.array(z.string().min(1)).optional();
+export const userEntrySchema = z.strictObject({
+    permissionSets: scopeList,
+    permissionSetGroups: scopeList,
+    permissionSetLicenses: scopeList,
+});
+export const fileSchema = z.strictObject({
+    users: z.record(z.string().min(1), userEntrySchema),
+});
+/** Validate a parsed object against the file contract, turning issues into findings. */
+export function validateFile(data, file) {
+    const parsed = fileSchema.safeParse(data);
+    if (parsed.success) {
+        return { data: parsed.data, findings: [] };
+    }
+    return {
+        findings: parsed.error.issues.map((issue) => ({
+            level: 'error',
+            code: 'SCHEMA',
+            message: `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+            file,
+        })),
+    };
+}
+//# sourceMappingURL=schema.js.map

package/lib/core/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AAExD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,YAAY,CAAC;IAC5C,cAAc,EAAE,SAAS;IACzB,mBAAmB,EAAE,SAAS;IAC9B,qBAAqB,EAAE,SAAS;CACjC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC;CACpD,CAAC,CAAC;AAIH,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,IAAY;IACtD,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC7C,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC5C,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE;YAChE,IAAI;SACL,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/lib/services/check.d.ts

@@ -0,0 +1,17 @@
+import { DesiredAssignment, Finding } from '../core/model.js';
+export type CheckOptions = {
+    files: string[];
+    strict: boolean;
+};
+export type CheckResult = {
+    files: string[];
+    assignments: DesiredAssignment[];
+    findings: Finding[];
+    errors: number;
+    warnings: number;
+    failed: boolean;
+};
+/** Offline check: load the files, validate them, and summarize the findings. */
+export declare class CheckService {
+    run(options: CheckOptions): Promise<CheckResult>;
+}

package/lib/services/check.js

@@ -0,0 +1,20 @@
+import { loadFiles } from '../core/load.js';
+import { countFindings } from '../core/report.js';
+/** Offline check: load the files, validate them, and summarize the findings. */
+export class CheckService {
+    // eslint-disable-next-line class-methods-use-this
+    async run(options) {
+        const loaded = await loadFiles(options.files);
+        const { errors, warnings } = countFindings(loaded.findings);
+        const failed = errors > 0 || (options.strict && warnings > 0);
+        return {
+            files: loaded.files,
+            assignments: loaded.assignments,
+            findings: loaded.findings,
+            errors,
+            warnings,
+            failed,
+        };
+    }
+}
+//# sourceMappingURL=check.js.map

package/lib/services/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/services/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAiBlD,gFAAgF;AAChF,MAAM,OAAO,YAAY;IACvB,kDAAkD;IAC3C,KAAK,CAAC,GAAG,CAAC,OAAqB;QACpC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;QAE9D,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM;YACN,QAAQ;YACR,MAAM;SACP,CAAC;IACJ,CAAC;CACF"}

package/messages/ps.check.md

@@ -0,0 +1,33 @@
+# summary
+
+Statically check permission set assignment files, with no org connection.
+
+# 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.
+
+# flags.file.summary
+
+YAML file or glob to check. Repeatable.
+
+# flags.strict.summary
+
+Treat warnings as errors.
+
+# summary.counts
+
+%s errors, %s warnings.
+
+# error.failed
+
+Check found problems. See the output above.
+
+# examples
+
+- Check every file under permissions:
+
+  <%= config.bin %> <%= command.id %> --file "permissions/*.yml"
+
+- Check specific files:
+
+  <%= config.bin %> <%= command.id %> --file permissions/sales.yml --file permissions/service.yml