Merge branch 'wr/nga' into wr/addMSO

Author: EstebanRomero84

command-snapshot.json

@@ -56,7 +56,7 @@
     "command": "agent:generate:authoring-bundle",
     "flagAliases": [],
     "flagChars": ["d", "f", "n", "o"],
-    "flags": ["api-version", "flags-dir", "json", "name", "output-dir", "spec", "target-org"],
+    "flags": ["api-name", "api-version", "flags-dir", "json", "name", "output-dir", "spec", "target-org"],
     "plugin": "@salesforce/plugin-agent"
   },
   {

messages/agent.generate.authoring-bundle.md

@@ -4,7 +4,7 @@ Generate an authoring bundle from an agent specification.
 
 # description
 
-Generates an authoring bundle containing AFScript and its meta.xml file from an agent specification file.
+Generates an authoring bundle containing Agent and its meta.xml file from an agent specification file.
 
 # flags.spec.summary
 
@@ -16,11 +16,15 @@ Directory where the authoring bundle files will be generated.
 
 # flags.name.summary
 
-Name (label) of the authoring bundle. If not provided, you will be prompted for it.
+Name (label) of the authoring bundle.
 
-# flags.name.prompt
+# flags.api-name.summary
 
-Name (label) of the authoring bundle
+API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name must not exist in the org.
+
+# flags.api-name.prompt
+
+API name of the new authoring bundle
 
 # examples
 
@@ -38,6 +42,6 @@ No agent specification file found at the specified path.
 
 The specified file is not a valid agent specification file.
 
-# error.failed-to-create-afscript
+# error.failed-to-create-agent
 
-Failed to create AFScript from the agent specification.
+Failed to create Agent from the agent specification.

messages/agent.preview.md

@@ -20,7 +20,7 @@ API name of the agent you want to interact with.
 
 # flags.authoring-bundle.summary
 
-Preview an ephemeral afscript agent by specifying the API name of the Authoring Bundle metadata
+Preview an ephemeral agent by specifying the API name of the Authoring Bundle metadata
 
 # flags.client-app.summary
 

messages/agent.publish.authoring-bundle.md

@@ -15,6 +15,10 @@ Publishes an Agent Authoring Bundle by compiling the AF script and creating a ne
 
 API name of the Agent Authoring Bundle to publish
 
+# flags.api-name.prompt
+
+API name of the authoring bundle to publish
+
 # flags.agent-name.summary
 
 Name for the new agent to be created
@@ -32,10 +36,10 @@ Invalid bundle path. Please provide a valid path to an Agent Authoring Bundle.
 Failed to publish agent with the following errors:
 %s
 
-# error.afscriptNotFound
+# error.agentNotFound
 
 Could not find an .agent file with API name '%s' in the project.
 
-# error.afscriptNotFoundAction
+# error.agentNotFoundAction
 
 Please check that the API name is correct and that the .agent file exists in your project directory.

messages/agent.validate.authoring-bundle.md

@@ -15,6 +15,10 @@ Validates an Agent Authoring Bundle by compiling the AF script and checking for
 
 Path to the Agent Authoring Bundle to validate
 
+# flags.api-name.prompt
+
+API name of the authoring bundle to validate
+
 # error.missingRequiredFlags
 
 Required flag(s) missing: %s
@@ -28,10 +32,10 @@ Invalid bundle path. Please provide a valid path to an Agent Authoring Bundle.
 AF Script compilation failed with the following errors:
 %s
 
-# error.afscriptNotFound
+# error.agentNotFound
 
 Could not find an .agent file with API name '%s' in the project.
 
-# error.afscriptNotFoundAction
+# error.agentNotFoundAction
 
 Please check that the API name is correct and that the .agent file exists in your project directory.

schemas/agent-generate-authoring__bundle.json

@@ -5,7 +5,7 @@
     "AgentGenerateAuthoringBundleResult": {
       "type": "object",
       "properties": {
-        "afScriptPath": {
+        "agentPath": {
           "type": "string"
         },
         "metaXmlPath": {
@@ -15,7 +15,7 @@
           "type": "string"
         }
       },
-      "required": ["afScriptPath", "metaXmlPath", "outputDir"],
+      "required": ["agentPath", "metaXmlPath", "outputDir"],
       "additionalProperties": false
     }
   }

src/commands/agent/generate/authoring-bundle.ts

@@ -14,19 +14,21 @@
  * limitations under the License.
  */
 
-import { join } from 'node:path';
-import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
-import { Messages, SfError } from '@salesforce/core';
+import { generateApiName, Messages, SfError } from '@salesforce/core';
 import { Agent, AgentJobSpec } from '@salesforce/agents';
 import YAML from 'yaml';
-import { FlaggablePrompt, promptForFlag } from '../../../flags.js';
+import { input as inquirerInput } from '@inquirer/prompts';
+import { theme } from '../../../inquirer-theme.js';
+import { FlaggablePrompt, promptForFlag, promptForYamlFile } from '../../../flags.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.generate.authoring-bundle');
 
 export type AgentGenerateAuthoringBundleResult = {
-  afScriptPath: string;
+  agentPath: string;
   metaXmlPath: string;
   outputDir: string;
 };
@@ -39,6 +41,9 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
 
   public static readonly flags = {
     'target-org': Flags.requiredOrg(),
+    'api-name': Flags.string({
+      summary: messages.getMessage('flags.api-name.summary'),
+    }),
     'api-version': Flags.orgApiVersion(),
     spec: Flags.file({
       summary: messages.getMessage('flags.spec.summary'),
@@ -58,13 +63,36 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
   private static readonly FLAGGABLE_PROMPTS = {
     name: {
       message: messages.getMessage('flags.name.summary'),
-      promptMessage: messages.getMessage('flags.name.prompt'),
-      validate: (d: string): boolean | string => d.length > 0 || 'Name cannot be empty',
+      validate: (d: string): boolean | string =>
+        d.trim().length > 0 || 'Name cannot be empty or contain only whitespace',
       required: true,
     },
+    'api-name': {
+      message: messages.getMessage('flags.api-name.summary'),
+      promptMessage: messages.getMessage('flags.api-name.prompt'),
+      validate: (d: string): boolean | string => {
+        if (d.length === 0) {
+          return true;
+        }
+        if (d.length > 80) {
+          return 'API name cannot be over 80 characters.';
+        }
+        const regex = /^[A-Za-z][A-Za-z0-9_]*[A-Za-z0-9]+$/;
+        if (!regex.test(d)) {
+          return 'Invalid API name.';
+        }
+        return true;
+      },
+    },
     spec: {
       message: messages.getMessage('flags.spec.summary'),
-      validate: (d: string): boolean | string => d.length > 0 || 'Spec file path cannot be empty',
+      validate: (d: string): boolean | string => {
+        const specPath = resolve(d);
+        if (!existsSync(specPath)) {
+          return 'Please enter an existing agent spec (yaml) file';
+        }
+        return true;
+      },
       required: true,
     },
   } satisfies Record<string, FlaggablePrompt>;
@@ -74,29 +102,42 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
     const { 'output-dir': outputDir, 'target-org': targetOrg } = flags;
 
     // If we don't have a spec yet, prompt for it
-    const spec = flags['spec'] ?? (await promptForFlag(AgentGenerateAuthoringBundle.FLAGGABLE_PROMPTS['spec']));
+    const spec = flags.spec ?? (await promptForYamlFile(AgentGenerateAuthoringBundle.FLAGGABLE_PROMPTS['spec']));
 
     // If we don't have a name yet, prompt for it
-    const name = (
-      flags['name'] ?? (await promptForFlag(AgentGenerateAuthoringBundle.FLAGGABLE_PROMPTS['name']))
-    ).replaceAll(' ', '_');
+    const name = flags['name'] ?? (await promptForFlag(AgentGenerateAuthoringBundle.FLAGGABLE_PROMPTS['name']));
+
+    // If we don't have an api name yet, prompt for it
+    let bundleApiName = flags['api-name'];
+    if (!bundleApiName) {
+      bundleApiName = generateApiName(name);
+      const promptedValue = await inquirerInput({
+        message: messages.getMessage('flags.api-name.prompt'),
+        validate: AgentGenerateAuthoringBundle.FLAGGABLE_PROMPTS['api-name'].validate,
+        default: bundleApiName,
+        theme,
+      });
+      if (promptedValue?.length) {
+        bundleApiName = promptedValue;
+      }
+    }
 
     try {
       // Get default output directory if not specified
       const defaultOutputDir = join(this.project!.getDefaultPackage().fullPath, 'main', 'default');
       const targetOutputDir = join(outputDir ?? defaultOutputDir, 'aiAuthoringBundles', name);
 
       // Generate file paths
-      const afScriptPath = join(targetOutputDir, `${name}.agent`);
+      const agentPath = join(targetOutputDir, `${name}.agent`);
       const metaXmlPath = join(targetOutputDir, `${name}.aiAuthoringBundle-meta.xml`);
 
-      // Write AFScript file
+      // Write Agent file
       const conn = targetOrg.getConnection(flags['api-version']);
       const specContents = YAML.parse(readFileSync(spec, 'utf8')) as AgentJobSpec;
-      const afScript = await Agent.createAfScript(conn, specContents);
+      const agent = await Agent.createAfScript(conn, specContents);
       // Create output directory if it doesn't exist
       mkdirSync(targetOutputDir, { recursive: true });
-      writeFileSync(afScriptPath, afScript);
+      writeFileSync(agentPath, agent);
 
       // Write meta.xml file
       const metaXml = `<?xml version="1.0" encoding="UTF-8"?>
@@ -113,15 +154,13 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
       this.logSuccess(`Successfully generated ${name} Authoring Bundle`);
 
       return {
-        afScriptPath,
+        agentPath,
         metaXmlPath,
         outputDir: targetOutputDir,
       };
     } catch (error) {
       const err = SfError.wrap(error);
-      throw new SfError(messages.getMessage('error.failed-to-create-afscript'), 'AfScriptGenerationError', [
-        err.message,
-      ]);
+      throw new SfError(messages.getMessage('error.failed-to-create-agent'), 'AgentGenerationError', [err.message]);
     }
   }
 }

src/commands/agent/publish/authoring-bundle.ts

@@ -22,6 +22,7 @@ import { Messages, Lifecycle, SfError } from '@salesforce/core';
 import { Agent, findAuthoringBundle } from '@salesforce/agents';
 import { RequestStatus, type ScopedPostRetrieve } from '@salesforce/source-deploy-retrieve';
 import { ensureArray } from '@salesforce/kit';
+import { FlaggablePrompt, promptForFlag } from '../../../flags.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.publish.authoring-bundle');
@@ -44,26 +45,45 @@ export default class AgentPublishAuthoringBundle extends SfCommand<AgentPublishA
     'api-name': Flags.string({
       char: 'n',
       summary: messages.getMessage('flags.api-name.summary'),
-      required: true,
     }),
   };
 
+  private static readonly FLAGGABLE_PROMPTS = {
+    'api-name': {
+      message: messages.getMessage('flags.api-name.summary'),
+      promptMessage: messages.getMessage('flags.api-name.prompt'),
+      validate: (d: string): boolean | string => {
+        if (d.length > 80) {
+          return 'API name cannot be over 80 characters.';
+        }
+        const regex = /^[A-Za-z][A-Za-z0-9_]*[A-Za-z0-9]+$/;
+        if (d.length === 0 || !regex.test(d)) {
+          return 'Invalid API name.';
+        }
+        return true;
+      },
+    },
+  } satisfies Record<string, FlaggablePrompt>;
+
   public async run(): Promise<AgentPublishAuthoringBundleResult> {
     const { flags } = await this.parse(AgentPublishAuthoringBundle);
+    // If we don't have an api name yet, prompt for it
+    const apiName =
+      flags['api-name'] ?? (await promptForFlag(AgentPublishAuthoringBundle.FLAGGABLE_PROMPTS['api-name']));
     // todo: this eslint warning can be removed once published
     // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-    const authoringBundleDir = findAuthoringBundle(this.project!.getPath(), flags['api-name']);
+    const authoringBundleDir = findAuthoringBundle(this.project!.getPath(), apiName);
 
     if (!authoringBundleDir) {
-      throw new SfError(messages.getMessage('error.afscriptNotFound', [flags['api-name']]), 'AfScriptNotFoundError', [
-        messages.getMessage('error.afscriptNotFoundAction'),
+      throw new SfError(messages.getMessage('error.agentNotFound', [apiName]), 'AgentNotFoundError', [
+        messages.getMessage('error.agentNotFoundAction'),
       ]);
     }
     // Create multi-stage output
     const mso = new MultiStageOutput<{ agentName: string }>({
       stages: ['Validate Bundle', 'Publish Agent', 'Retrieve Metadata'],
       title: 'Publishing Agent',
-      data: { agentName: flags['api-name'] },
+      data: { agentName: apiName },
       jsonEnabled: this.jsonEnabled(),
       postStagesBlock: [
         {
@@ -83,7 +103,7 @@ export default class AgentPublishAuthoringBundle extends SfCommand<AgentPublishA
       // First compile the AF script to get the Agent JSON
       const agentJson = await Agent.compileAfScript(
         conn,
-        readFileSync(join(authoringBundleDir, `${flags['api-name']}.agent`), 'utf8')
+        readFileSync(join(authoringBundleDir, `${apiName}.agent`), 'utf8')
       );
       mso.skipTo('Publish Agent');
 

src/commands/agent/validate/authoring-bundle.ts

@@ -21,6 +21,7 @@ import { MultiStageOutput } from '@oclif/multi-stage-output';
 import { Agent, findAuthoringBundle } from '@salesforce/agents';
 import { Duration, sleep } from '@salesforce/kit';
 import { colorize } from '@oclif/core/ux';
+import { FlaggablePrompt, promptForFlag } from '../../../flags.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.validate.authoring-bundle');
@@ -42,16 +43,37 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
     'api-name': Flags.string({
       char: 'n',
       summary: messages.getMessage('flags.api-name.summary'),
-      required: true,
     }),
   };
 
+  private static readonly FLAGGABLE_PROMPTS = {
+    'api-name': {
+      message: messages.getMessage('flags.api-name.summary'),
+      promptMessage: messages.getMessage('flags.api-name.prompt'),
+      validate: (d: string): boolean | string => {
+        if (d.length > 80) {
+          return 'API name cannot be over 80 characters.';
+        }
+        const regex = /^[A-Za-z][A-Za-z0-9_]*[A-Za-z0-9]+$/;
+        if (d.length === 0 || !regex.test(d)) {
+          return 'Invalid API name.';
+        }
+        return true;
+      },
+    },
+  } satisfies Record<string, FlaggablePrompt>;
+
   public async run(): Promise<AgentValidateAuthoringBundleResult> {
     const { flags } = await this.parse(AgentValidateAuthoringBundle);
-    const authoringBundleDir = findAuthoringBundle(this.project!.getPath(), flags['api-name']);
+    // If we don't have an api name yet, prompt for it
+    const apiName =
+      flags['api-name'] ?? (await promptForFlag(AgentValidateAuthoringBundle.FLAGGABLE_PROMPTS['api-name']));
+    // todo: this eslint warning can be removed once published
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    const authoringBundleDir = findAuthoringBundle(this.project!.getPath(), apiName);
     if (!authoringBundleDir) {
-      throw new SfError(messages.getMessage('error.afscriptNotFound', [flags['api-name']]), 'AfScriptNotFoundError', [
-        messages.getMessage('error.afscriptNotFoundAction'),
+      throw new SfError(messages.getMessage('error.agentNotFound', [apiName]), 'AgentNotFoundError', [
+        messages.getMessage('error.agentNotFoundAction'),
       ]);
     }
     const mso = new MultiStageOutput<{ status: string; errors: string }>({
@@ -81,7 +103,7 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
       const conn = targetOrg.getConnection(flags['api-version']);
       // Call Agent.compileAfScript() API
       await sleep(Duration.seconds(2));
-      await Agent.compileAfScript(conn, readFileSync(join(authoringBundleDir, `${flags['api-name']}.agent`), 'utf8'));
+      await Agent.compileAfScript(conn, readFileSync(join(authoringBundleDir, `${!apiName}.agent`), 'utf8'));
       mso.updateData({ status: 'COMPLETED' });
       mso.stop('completed');
       return {