feat: enhance permset migration with wildcard support and strict validation

- Added support for wildcard expansion in permission specifications (e.g., `Object.*`).
- Introduced a `--strict` flag to enforce validation of target fields and objects during migration.
- Updated metadata validation to skip or throw errors based on the strictness setting.
- Improved documentation in README and message files to reflect new features and usage examples.
- Added tests for new functionality, including wildcard expansion and strict validation scenarios.

Author: renatoliveira

README.md

@@ -172,10 +172,13 @@ _See code: [src/commands/migrate/permset/copy.ts](https://github.com/wisefox/plu
 - Permission sets are matched across orgs by **API name** (`PermissionSet.Name`) and **NamespacePrefix**. If the same API name exists in different namespaces, resolve collisions by ensuring metadata is unambiguous on both sides.
 - Only permission sets that already exist on the **target** are updated. Source-only permission sets are reported in JSON output under `skippedPermissionSets` and are not created on the target.
 - **Object-only** tokens (e.g. `Account`) sync **ObjectPermissions** for that object for **every matched** permission set on both orgs. **Field** tokens sync **FieldPermissions** only for that field; if you do **not** pass any object-only token, object-level rows for that object are synced only for permission sets that have source field rows. If you pass **both** (e.g. `Account,Account.Name`), object-level sync covers all matched sets for the objects in your `--perms` list, and the source query includes **ObjectPermissions** for every matched permission set so rows are not missed when discovery omitted a parent.
-- DML order on the target is: insert **ObjectPermissions** then **FieldPermissions**, then updates in the same order, then delete **FieldPermissions** then **ObjectPermissions**, so object rows exist before field rows and revokes remove field rows before object rows.
+- DML order on the target is: insert **ObjectPermissions** then **FieldPermissions**, then updates in the same order, then delete **FieldPermissions** then **ObjectPermissions**, so object rows exist before field rows and revokes remove field rows before object rows. Field/Object permission **deletes** use one REST **DELETE per record Id** (not the composite `?ids=` batch) for compatibility with Salesforce responses. Query rows normalize `Id` / `id` from the API.
+  - **`Object.*` (or `Object:*`)** expands to fields on that object where Tooling **FieldDefinition** reports **IsFlsEnabled** (same idea as “permissionable” in describe). The field list is resolved on the **source** org via the Tooling API (metadata, not the user’s FLS visibility). By default, fields (or whole objects) that are missing on the **target** are **skipped** with a warning; use **`--strict`** to fail instead if anything in `--perms` is absent on the target.
+- Schema checks use the **Tooling API** (`FieldDefinition`, `EntityDefinition`). The integration user needs access to Tooling (e.g. **View Setup and Configuration** or equivalent), not only FLS on the fields being migrated. `FieldDefinition` SOQL filters use the `EntityDefinition` relationship in the `WHERE` clause (not only `FROM FieldDefinition`).
+- **Field sync** only considers `FieldPermissions` rows whose **`SobjectType`** matches an object from `--perms` (e.g. `Contact.*` ignores unrelated rows such as other entities that can appear in broad queries). That avoids diffing or deleting FLS for objects you did not request.
 
 ### Salesforce API references
 
 - [FieldPermissions](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_fieldpermissions.htm)
-- [ObjectPermissions](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_objectpermissions.htm)
+- [ObjectPermissions](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_objectpermissions.htm) — includes `PermissionsViewAllFields` (API v63.0+) for object-level “View All Fields”.
 - [PermissionSet](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_permissionset.htm)

messages/migrate.permset.copy.md

@@ -8,13 +8,18 @@ Provide one or more permission targets with `--perms`:
 
 - **Object only** (e.g. `Account`) — syncs **ObjectPermissions** for that object (create/read/edit/delete, etc.). Does not read FieldPermissions for that token.
 - **Field** (`Object.Field` or `Object:Field`, e.g. `Account.Name`) — syncs **FieldPermissions** for that field. Object-level permissions for that object are also synced for permission sets that have source field rows (narrow scope).
+- **All fields on an object** (`Object.*` or `Object:*`) — expands to every field on that object that is **FLS-enabled** in metadata (Tooling **FieldDefinition** / `IsFlsEnabled` on the **source** org), then syncs FieldPermissions like individual field tokens. Wildcard expansion uses the Tooling API so the list does not depend on the user’s field visibility.
 
-You may mix tokens in one command (e.g. `Account,Contact.Email`).
+You may mix tokens in one command (e.g. `Account,Contact.Email` or `Contact.*`).
 
 Queries FieldPermissions and ObjectPermissions on the source and target orgs as needed, matches permission sets by API name (PermissionSet.Name) and NamespacePrefix, computes the diff (source is the source of truth), then applies inserts, updates, and deletes on the target.
 
+Wildcard expansion and preflight validation use the **Tooling API** (`FieldDefinition`, `EntityDefinition`) so object and field names come from org metadata; the running user must have Tooling access (e.g. View Setup and Configuration), not only FLS on the migrated fields.
+
 By default, only permission sets with IsOwnedByProfile = false are considered. Use --include-profile-owned to include profile-owned (shadow) permission sets.
 
+By default, fields (and objects) that are not present on the **target** org are **skipped** with a warning so the rest of the migration still runs. Use **--strict** to fail the command instead when anything in `--perms` is missing on the target.
+
 # examples
 
 - Copy FLS for two fields between aliases `org1` and `org2`:
@@ -29,6 +34,10 @@ By default, only permission sets with IsOwnedByProfile = false are considered. U
 
   <%= config.bin %> <%= command.id %> -s org1 -t org2 --perms "Object**c:Field**c" --include-profile-owned
 
+- Sync all permissionable Contact fields (wildcard):
+
+  <%= config.bin %> <%= command.id %> -s org1 -t org2 --perms "Contact.\*"
+
 # flags.source-org.summary
 
 Username or alias of the org to read permissions from.
@@ -39,12 +48,16 @@ Username or alias of the org to update.
 
 # flags.perms.summary
 
-Comma-separated list: object API name for object-level permissions only, or Object.Field / Object:Field for field-level (FLS) permissions only.
+Comma-separated list: object API name for object-level permissions only; Object.Field or Object:Field for one field; Object._ or Object:_ for all FLS-enabled fields on that object (expanded using Tooling FieldDefinition on the source org).
 
 # flags.include-profile-owned.summary
 
 Include permission sets owned by profiles (IsOwnedByProfile = true).
 
+# flags.strict.summary
+
+Fail if any object or field from --perms is missing on the target org. When omitted, missing target fields/objects are skipped with warnings.
+
 # errors.SourceOrgRequired
 
 You must provide a source org username or alias with --source-org.
@@ -61,6 +74,10 @@ Source and target org must be different usernames.
 
 Provide at least one object or field in --perms.
 
+# errors.NoSpecsRemain
+
+Nothing remains to sync after matching the target org (all targets were missing on the target). Broaden --perms or use a source org that aligns with the target, or use --strict to see the first validation error instead.
+
 # info.start
 
 Syncing permission sets for %s permission target(s)...

src/commands/migrate/permset/copy.ts

@@ -4,8 +4,10 @@
 
 import { Messages, Org, SfError } from '@salesforce/core';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { expandPermWildcards } from '../../../shared/expandPermWildcards.js';
 import { parsePerms } from '../../../shared/fields.js';
 import { validatePermMetadata } from '../../../shared/metadata.js';
+import type { FieldNameCache } from '../../../shared/toolingSchema.js';
 import { syncPermissionSets, type SyncResult } from '../../../shared/syncPermissions.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
@@ -36,13 +38,16 @@ export default class MigratePermsetCopy extends SfCommand<SyncResult> {
     'include-profile-owned': Flags.boolean({
       summary: messages.getMessage('flags.include-profile-owned.summary'),
     }),
+    strict: Flags.boolean({
+      summary: messages.getMessage('flags.strict.summary'),
+    }),
     'api-version': Flags.orgApiVersion(),
   };
 
   public async run(): Promise<SyncResult> {
     const { flags } = await this.parse(MigratePermsetCopy);
 
-    // 1) Parse --perms; 2) resolve orgs; 3) describe metadata; 4) sync on target.
+    // 1) Parse --perms; 2) resolve orgs; 3) Tooling schema validation; 4) sync on target.
     let specs;
     try {
       specs = parsePerms(flags.perms);
@@ -66,12 +71,35 @@ export default class MigratePermsetCopy extends SfCommand<SyncResult> {
     const source = sourceOrg.getConnection(flags['api-version']);
     const target = targetOrg.getConnection(flags['api-version']);
 
-    const { warnings: metaWarnings } = await validatePermMetadata(source, target, specs);
+    const sourceFieldCache: FieldNameCache = new Map();
+    const targetFieldCache: FieldNameCache = new Map();
+
+    let expanded;
+    try {
+      expanded = await expandPermWildcards(source, specs, sourceFieldCache);
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      throw new SfError(err.message, 'WildcardExpandError');
+    }
+
+    if (expanded.length === 0) {
+      throw messages.createError('errors.EmptyPerms');
+    }
+
+    const { warnings: metaWarnings, specs: validatedSpecs } = await validatePermMetadata(source, target, expanded, {
+      sourceFieldCache,
+      targetFieldCache,
+      strict: Boolean(flags.strict),
+    });
+
+    if (validatedSpecs.length === 0) {
+      throw messages.createError('errors.NoSpecsRemain');
+    }
 
-    this.log(messages.getMessage('info.start', [String(specs.length)]));
+    this.log(messages.getMessage('info.start', [String(validatedSpecs.length)]));
 
     const profileOwned = Boolean(flags['include-profile-owned']);
-    const result = await syncPermissionSets(source, target, specs, profileOwned, metaWarnings);
+    const result = await syncPermissionSets(source, target, validatedSpecs, profileOwned, metaWarnings);
 
     if (result.skippedPermissionSets.length > 0) {
       this.warn(messages.getMessage('info.skippedPs', [String(result.skippedPermissionSets.length)]));

src/shared/expandPermWildcards.ts

@@ -0,0 +1,47 @@
+import type { Connection } from '@salesforce/core';
+import type { FieldPermSpec, PermSpec } from './fields.js';
+import type { FieldNameCache } from './toolingSchema.js';
+import { loadPermissionableFieldNamesForEntity } from './toolingSchema.js';
+
+/** Dedupe object and field entries after wildcard expansion. */
+function dedupePermSpecs(specs: PermSpec[]): PermSpec[] {
+  const m = new Map<string, PermSpec>();
+  for (const s of specs) {
+    if (s.kind === 'object') {
+      m.set(s.canonical, s);
+    } else if (s.kind === 'field') {
+      m.set(s.canonicalField, s);
+    }
+  }
+  return [...m.values()];
+}
+
+/**
+ * Replace each `Object.*` token with concrete `FieldPermSpec` rows using Tooling `FieldDefinition` on `conn`
+ * (typically the source org). Listing is metadata-based and does not depend on FLS visibility for the user.
+ */
+export async function expandPermWildcards(
+  conn: Connection,
+  specs: PermSpec[],
+  fieldNameCache?: FieldNameCache
+): Promise<PermSpec[]> {
+  const chunks = await Promise.all(
+    specs.map(async (s) => {
+      if (s.kind !== 'fieldWildcard') {
+        return [s];
+      }
+      const fieldNames = await loadPermissionableFieldNamesForEntity(conn, s.objectApiName, fieldNameCache);
+      const fields: FieldPermSpec[] = [];
+      for (const fieldApiName of fieldNames) {
+        fields.push({
+          kind: 'field',
+          objectApiName: s.objectApiName,
+          fieldApiName,
+          canonicalField: `${s.objectApiName}.${fieldApiName}`,
+        });
+      }
+      return fields;
+    })
+  );
+  return dedupePermSpecs(chunks.flat());
+}

src/shared/fields.ts

@@ -19,7 +19,18 @@ export type FieldPermSpec = {
   canonicalField: string;
 };
 
-export type PermSpec = ObjectPermSpec | FieldPermSpec;
+/**
+ * Expands to one FieldPermSpec per permissionable field on the object (Tooling FieldDefinition on the source org).
+ * Parse `Object.*` or `Object:*`.
+ */
+export type FieldWildcardSpec = {
+  kind: 'fieldWildcard';
+  objectApiName: string;
+  /** e.g. `Contact.*` */
+  canonical: string;
+};
+
+export type PermSpec = ObjectPermSpec | FieldPermSpec | FieldWildcardSpec;
 
 /** Split one token on the first `.` or `:` (whichever appears first if both exist). Returns null if neither. */
 function firstObjectFieldSeparator(token: string): number {
@@ -32,8 +43,8 @@ function firstObjectFieldSeparator(token: string): number {
 }
 
 /**
- * Comma-separated tokens: `Account` (object perms only), or `Object.Field` / `Object:Field` (field perms only).
- * Deduped by canonical string per token kind.
+ * Comma-separated tokens: `Account` (object perms only), `Object.*` (all permissionable fields), or
+ * `Object.Field` / `Object:Field` (single field). Deduped by canonical string per token kind.
  */
 export function parsePerms(raw: string): PermSpec[] {
   const parts = raw
@@ -59,6 +70,13 @@ export function parsePerms(raw: string): PermSpec[] {
     if (!objectApiName || !fieldApiName) {
       throw new Error(`Invalid permission token "${p}": expected Object.Field or Object:Field`);
     }
+    if (fieldApiName === '*') {
+      const canonical = `${objectApiName}.*`;
+      if (!byCanon.has(canonical)) {
+        byCanon.set(canonical, { kind: 'fieldWildcard', objectApiName, canonical });
+      }
+      continue;
+    }
     const canonicalField = `${objectApiName}.${fieldApiName}`;
     if (!byCanon.has(canonicalField)) {
       byCanon.set(canonicalField, { kind: 'field', objectApiName, fieldApiName, canonicalField });
@@ -67,7 +85,7 @@ export function parsePerms(raw: string): PermSpec[] {
   return [...byCanon.values()];
 }
 
-/** Distinct object API names from all permission specs (field + object-only). */
+/** Distinct object API names from all permission specs (field, wildcard, and object-only). */
 export function uniqueObjectNamesFromPerms(specs: PermSpec[]): string[] {
   return [...new Set(specs.map((s) => s.objectApiName))];
 }