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

package/README.md

@@ -21,6 +21,7 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Commands](#commands)
 - [Inspiration & equivalents](#inspiration--equivalents)
 - [Versioning](#versioning)
+- [Architecture](#architecture)
 
 ---
 
@@ -196,11 +197,12 @@ 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)
@@ -210,15 +212,18 @@ CHECKS
   - 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.
@@ -228,13 +233,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:
@@ -335,6 +341,25 @@ 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.
 
+## Architecture
+
+The plugin is layered so every command reuses the same core. Commands stay thin, services hold the orchestration, and core holds the reusable primitives.
+
+- **Commands** (`src/commands/ps/`): oclif only. Parse flags, call a service, render output, set the exit code.
+- **Services** (`src/services/`): one per command (`check` today, then `validate`, `plan`, `apply`, `export`). Each turns the core into a command's behavior.
+- **Core** (`src/core/`): the reusable building blocks.
+
+| Core module | Responsibility |
+| --- | --- |
+| `model` | Shared domain types (assignment, finding, result). |
+| `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. |
+| `load` | Expand globs, run parse then validate then normalize per file, and merge by union. |
+| `report` | Format and count findings. |
+
+Commands are slices of one pipeline. `check` runs the offline **load** stage only. The online commands add **resolve** (names to ids), **fetch** (current org state), **diff** (desired vs actual), and **apply** (DML) on top, reusing load, report, model, and schema unchanged.
+
 ## License
 
 BSD-3-Clause © Isaac Ferreira

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 { check } 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 check({ files: flags.file, strict: flags.strict });
+        for (const line of formatFindings(result.findings)) {
+            this.log(line);
+        }
+        const assignees = new Set(result.assignments.map((a) => a.assignee));
+        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: assignees.size,
+            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,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,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;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,MAAM,CAAU,KAAK,GAAG;QAC3B,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;YACf,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,oBAAoB,CAAC;YAClD,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,IAAI;SACjB,CAAC;QACF,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC;YAClB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC;SACvD,CAAC;KACL,CAAC;IAEK,KAAK,CAAC,GAAG;QACZ,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAExE,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrE,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;YAChB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;gBACtB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;YACjE,CAAC;QACL,CAAC;QAED,OAAO;YACH,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;YAC1B,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM;YACtC,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC5B,CAAC;IACN,CAAC"}

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

@@ -1 +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"}
+{"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;IAC9C,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;QACZ,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;IACjC,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;IACnD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC1D,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;IACtF,CAAC;IAED,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO;QACH,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC;KAChF,CAAC;AACN,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAkB;IAC9C,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;YACH,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;SACxG,CAAC;IACN,CAAC;IAED,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAwB,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,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;IACvC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,WAAW,GAAwB,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QACxB,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;IACxB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAC5C,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;IACvC,CAAC,eAAe,EAAE,gBAAgB,CAAC;IACnC,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;IAC7C,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;CACpD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,IAAY;IACnD,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;QACzD,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,IAAI,KAAK,SAAS;gBAAE,SAAS;YACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpB,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;YACb,CAAC;YAED,UAAU,IAAI,CAAC,CAAC;YAChB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,KAAK,MAAM,MAAM,IAAI,IAAI,EAAE,CAAC;gBACxB,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACnB,QAAQ,CAAC,IAAI,CAAC;wBACV,KAAK,EAAE,SAAS;wBAChB,IAAI,EAAE,YAAY;wBAClB,OAAO,EAAE,GAAG,QAAQ,KAAK,MAAM,0BAA0B,GAAG,EAAE;wBAC9D,IAAI;qBACP,CAAC,CAAC;oBACH,SAAS;gBACb,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;YAC3D,CAAC;QACL,CAAC;QAED,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,QAAQ,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9G,CAAC;IACL,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACrC,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;IAChD,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;QACxB,OAAO;YACH,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAC/B,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;aAC/B,CAAC,CAAC;SACN,CAAC;IACN,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAa,CAAC;IACnC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACpG,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAClC,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;IAC9C,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC5B,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;IAC1D,CAAC,CAAC,CAAC;AACP,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,aAAa,CAAC,QAAmB;IAC7C,OAAO;QACH,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;KACjE,CAAC;AACN,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;IAC1C,cAAc,EAAE,SAAS;IACzB,mBAAmB,EAAE,SAAS;IAC9B,qBAAqB,EAAE,SAAS;CACnC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC;CACtD,CAAC,CAAC;AAIH,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,IAAY;IACpD,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO;QACH,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC1C,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;SACP,CAAC,CAAC;KACN,CAAC;AACN,CAAC"}

package/lib/services/check.d.ts

@@ -0,0 +1,15 @@
+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 function check(options: CheckOptions): Promise<CheckResult>;

package/lib/services/check.js

@@ -0,0 +1,17 @@
+import { loadFiles } from '../core/load.js';
+import { countFindings } from '../core/report.js';
+/** Offline check: load the files, validate them, and summarize the findings. */
+export async function check(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,CAAC,KAAK,UAAU,KAAK,CAAC,OAAqB;IAC7C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;IAE9D,OAAO;QACH,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM;QACN,QAAQ;QACR,MAAM;KACT,CAAC;AACN,CAAC"}

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