fix: make api-name flag prompt-able and rename AfScript to Agent

Author: EstebanRomero84

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
 
@@ -42,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

@@ -28,7 +28,7 @@ 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;
 };
@@ -128,16 +128,16 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
       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"?>
@@ -154,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

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { Messages, SfError } from '@salesforce/core';
 import { Agent, findAuthoringBundle } from '@salesforce/agents';
+import { FlaggablePrompt, promptForFlag } from '../../../flags.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.validate.authoring-bundle');
@@ -39,26 +40,45 @@ 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);
+    // 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(), 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'),
       ]);
     }
 
     try {
       const targetOrg = flags['target-org'];
       const conn = targetOrg.getConnection(flags['api-version']);
       // Call Agent.compileAfScript() API
-      await Agent.compileAfScript(conn, readFileSync(join(authoringBundleDir, `${flags['api-name']}.agent`), 'utf8'));
+      await Agent.compileAfScript(conn, readFileSync(join(authoringBundleDir, `${!apiName}.agent`), 'utf8'));
       this.logSuccess('Successfully compiled');
       return {
         success: true,

test/nuts/agent.generate.authoring-bundle.nut.ts

@@ -60,18 +60,18 @@ describe.skip('agent generate authoring-bundle NUTs', () => {
       const result = execCmd<AgentGenerateAuthoringBundleResult>(command, { ensureExitCode: 0 }).jsonOutput?.result;
 
       expect(result).to.be.ok;
-      expect(result?.afScriptPath).to.be.ok;
+      expect(result?.agentPath).to.be.ok;
       expect(result?.metaXmlPath).to.be.ok;
       expect(result?.outputDir).to.be.ok;
 
       // Verify files exist
-      expect(existsSync(result!.afScriptPath)).to.be.true;
+      expect(existsSync(result!.agentPath)).to.be.true;
       expect(existsSync(result!.metaXmlPath)).to.be.true;
 
       // Verify file contents
-      const afScript = readFileSync(result!.afScriptPath, 'utf8');
+      const agent = readFileSync(result!.agentPath, 'utf8');
       const metaXml = readFileSync(result!.metaXmlPath, 'utf8');
-      expect(afScript).to.be.ok;
+      expect(agent).to.be.ok;
       expect(metaXml).to.include('<aiAuthoringBundle>');
       expect(metaXml).to.include(bundleName);
     });