feat: align json definition file fields with cli flags and enforce required flags

Author: ukanoja-sf

README.md

@@ -115,14 +115,15 @@ Provision Permission Set Licenses (PSL) into a target org.
 
 ```
 USAGE
-  $ sf license provision -o <value> [-n <value>] [-l <value>] [-q <value>] [-f <value>] [--api-version <value>] [--json] [--flags-dir <value>]
+  $ sf license provision -o <value> [-l <value> -n <value> -q <value>] [-f <value>] [--api-version <value>] [--json] [--flags-dir <value>]
 
 FLAGS
   -f, --definition-file=<value>  Path to a JSON file that contains the PSL provisioning request information.
-  -l, --license=<value>          Permission Set License name.
-  -n, --namespace=<value>        License package namespace.
+                                 Cannot be combined with --license, --namespace, or --quantity.
+  -l, --license=<value>          Permission Set License name. Cannot be combined with --definition-file.
+  -n, --namespace=<value>        License package namespace. Requires --license. Cannot be combined with --definition-file.
   -o, --target-org=<value>       (required) Username or alias of the target org.
-  -q, --quantity=<value>         Number of licenses to provision.
+  -q, --quantity=<value>         Number of licenses to provision. Requires --license. Cannot be combined with --definition-file.
       --api-version=<value>      Override the api version used for api requests made by this command.
 
 GLOBAL FLAGS
@@ -134,41 +135,33 @@ DESCRIPTION
 
   There are two ways to run this command. You can provide the information to identify a single PSL via command line flags, or provision multiple PSLs in a single call by supplying a JSON formatted file.
 
-  See <Add URL Here> for the format and options contained within the JSON file.
+  The JSON definition file must contain a top-level `licenses` array. Each entry supports the following fields:
 
-EXAMPLES
-  Provision a single Permission Set License into an org:
-
-    $ sf license provision --target-org myScratchOrg --namespace demo --license newLicense --quantity 5
-
-  Use a JSON formatted input file to provision one or more Permission Set Licenses into an org:
+  | Field | Type | Required | Description |
+  |---|---|---|---|
+  | `license` | string | Yes | Permission Set License name. |
+  | `namespace` | string | Yes | License package namespace. |
+  | `quantity` | integer | Yes | Number of licenses to provision. |
 
-    $ sf license provision --target-org myScratchOrg --definition-file test/config/provisionPSLs.json
-
-HUMAN READABLE OUTPUT
+  Example:
 
-  Success:
-  Provisioned 5 licenses for the license definition 'demo__newLicense'
+  json
+  {
+    "licenses": [
+      { "namespace": "myNS", "license": "premiumLicense", "quantity": 10 },
+      { "namespace": "myNS", "license": "starterLicense", "quantity": 5 }
+    ]
+  }
 
-  Success:
-  Provisioned 5 licenses for the license definition 'demo__newLicense'
-  Provisioned 8 licenses for the license definition 'demo__premiumLicense'
+EXAMPLES
+Provision a single Permission Set License into an org:
 
-  Error: Failed to provision licenses.
-  License Definition not found for 'demo__badLicense'.
-  Quantity cannot be negative for 'demo__negativeLicense'.
+    $ sf license provision --target-org myScratchOrg --namespace demo --license newLicense --quantity 5
 
-JSON OUTPUT
+Use a JSON formatted input file to provision one or more Permission Set Licenses into an org:
 
-  { "status": "success" }
+    $ sf license provision --target-org myScratchOrg --definition-file test/config/provisionPSLs.json
 
-  {
-    "status": "error",
-    "messages": [
-      { "errorCode": "INVALID_LICENSE_DEFINITION", "message": "License definition not found for 'demo__badLicense'" },
-      { "errorCode": "INVALID_QUANTITY", "message": "Quantity cannot be negative for 'demo__negativeLicense'" }
-    ]
-  }
 ```
 
 _See code: [src/commands/license/provision.ts](https://github.com/salesforcecli/plugin-license-management/blob/1.0.0/src/commands/license/provision.ts)_

messages/license.provision.md

@@ -44,14 +44,18 @@ Trace ID: %s
 
 Either --license or --definition-file is required.
 
-# error.mutuallyExclusiveFlags
-
-The --definition-file flag cannot be used with --namespace, --license, or --quantity.
-
 # error.emptyDefinitionFile
 
 The definition file must contain at least one license entry.
 
+# error.unsupportedDefinitionFileFields
+
+Nonexistent fields: %s
+
+# error.missingRequiredDefinitionFileFields
+
+Missing required fields: %s
+
 # error.provisionFailed
 
 Failed to provision licenses. %s

src/commands/license/provision.ts

@@ -22,15 +22,25 @@ Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-license-management', 'license.provision');
 
 type ProvisionLicenseSpec = {
+  namespace?: string;
+  license?: string;
+  quantity?: number;
+};
+
+type ApiLicenseSpec = {
   namespacePrefix?: string;
   permissionSetLicense?: string;
   quantity?: number;
 };
 
-type ProvisionPslRequest = {
+type DefinitionFile = {
   licenses: ProvisionLicenseSpec[];
 };
 
+type ProvisionPslRequest = {
+  licenses: ApiLicenseSpec[];
+};
+
 type ProvisionPslResponse = {
   status: string;
   licensesProvisioned?: number;
@@ -44,8 +54,16 @@ export type LicenseProvisionResult = {
 };
 
 function getLicenseDefinitionName(spec: ProvisionLicenseSpec): string {
-  const psl = spec.permissionSetLicense ?? '';
-  return spec.namespacePrefix ? `${spec.namespacePrefix}__${psl}` : psl;
+  const psl = spec.license ?? '';
+  return spec.namespace ? `${spec.namespace}__${psl}` : psl;
+}
+
+function toApiSpec(spec: ProvisionLicenseSpec): ApiLicenseSpec {
+  return {
+    namespacePrefix: spec.namespace,
+    permissionSetLicense: spec.license,
+    quantity: spec.quantity,
+  };
 }
 
 export default class LicenseProvision extends SfCommand<LicenseProvisionResult> {
@@ -59,40 +77,57 @@ export default class LicenseProvision extends SfCommand<LicenseProvisionResult>
     namespace: Flags.string({
       char: 'n',
       summary: messages.getMessage('flags.namespace.summary'),
+      dependsOn: ['license'],
+      exclusive: ['definition-file'],
     }),
     license: Flags.string({
       char: 'l',
       summary: messages.getMessage('flags.license.summary'),
+      exclusive: ['definition-file'],
+      relationships: [{ type: 'all', flags: ['namespace', 'quantity'] }],
     }),
     quantity: Flags.integer({
       char: 'q',
       summary: messages.getMessage('flags.quantity.summary'),
       min: 0,
       max: Number.MAX_SAFE_INTEGER,
+      dependsOn: ['license'],
+      exclusive: ['definition-file'],
     }),
     'definition-file': Flags.string({
       char: 'f',
       summary: messages.getMessage('flags.definition-file.summary'),
+      exclusive: ['license', 'namespace', 'quantity'],
     }),
   };
 
   // Protected to allow stubbing in tests
-  protected static async loadSpecsFromFile(
-    filePath: string,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    flags: Record<string, any>
-  ): Promise<ProvisionLicenseSpec[]> {
-    if (flags['license'] || flags['namespace'] || flags['quantity'] !== undefined) {
-      throw messages.createError('error.mutuallyExclusiveFlags');
-    }
-
+  protected static async loadSpecsFromFile(filePath: string): Promise<ProvisionLicenseSpec[]> {
     const fileContent = await readFile(filePath, 'utf-8');
-    const definition = JSON.parse(fileContent) as ProvisionPslRequest;
+    const definition = JSON.parse(fileContent) as DefinitionFile;
 
     if (!Array.isArray(definition.licenses) || definition.licenses.length === 0) {
       throw messages.createError('error.emptyDefinitionFile');
     }
 
+    const allowedFields: ReadonlySet<string> = new Set(['namespace', 'license', 'quantity']);
+    const unknownFields = [
+      ...new Set(definition.licenses.flatMap((entry) => Object.keys(entry).filter((key) => !allowedFields.has(key)))),
+    ];
+    if (unknownFields.length > 0) {
+      throw messages.createError('error.unsupportedDefinitionFileFields', [unknownFields.join(', ')]);
+    }
+
+    const requiredFields = ['namespace', 'license', 'quantity'] as const;
+    const missingFields = definition.licenses.flatMap((entry, index) =>
+      requiredFields
+        .filter((field) => entry[field] === undefined || entry[field] === null)
+        .map((field) => `licenses[${index}].${field}`)
+    );
+    if (missingFields.length > 0) {
+      throw messages.createError('error.missingRequiredDefinitionFileFields', [missingFields.join(', ')]);
+    }
+
     return definition.licenses;
   }
 
@@ -104,8 +139,8 @@ export default class LicenseProvision extends SfCommand<LicenseProvisionResult>
 
     return [
       {
-        namespacePrefix: flags['namespace'] as string | undefined,
-        permissionSetLicense: flags['license'] as string,
+        namespace: flags['namespace'] as string | undefined,
+        license: flags['license'] as string,
         quantity: flags['quantity'] as number | undefined,
       },
     ];
@@ -117,11 +152,11 @@ export default class LicenseProvision extends SfCommand<LicenseProvisionResult>
     const connection = flags['target-org'].getConnection(flags['api-version']);
 
     const licenseSpecs = flags['definition-file']
-      ? await LicenseProvision.loadSpecsFromFile(flags['definition-file'], flags)
+      ? await LicenseProvision.loadSpecsFromFile(flags['definition-file'])
       : LicenseProvision.buildSpecsFromFlags(flags);
 
     const endpoint = `/services/data/v${connection.getApiVersion()}/partnerdevelopment/permissionsetlicenses`;
-    const requestBody: ProvisionPslRequest = { licenses: licenseSpecs };
+    const requestBody: ProvisionPslRequest = { licenses: licenseSpecs.map(toApiSpec) };
 
     let response: ProvisionPslResponse;
     try {