feat: app template list shows the newest version of each template, and describe says much more

src/cli/app/app-template-describe.ts

@@ -4,7 +4,6 @@ import * as s from '../../help/SampleData';
 import { describeApplicationTemplate } from '../../ops/ApplicationTemplateOps';
 import { getTokens } from '../../ops/AuthenticateOps';
 import c from '../../utils/ColorTheme';
-import { printMessage } from '../../utils/Console.js';
 import { positionalValue } from '../../utils/interactive/PositionalArgs';
 import { FrodoCommand } from '../FrodoCommand';
 import { channelOption, templatesOption } from './app-template-options';
@@ -25,12 +24,32 @@ export default function setup() {
   );
 
   program
-    .description('Describe an application template.')
+    .description(
+      'Describe an application template: what it provides, its versions, connector, capabilities, object types and application form. The newest version unless -v names another.'
+    )
     .addOption(
       new Option(
         '-i, --template-id <template-id>',
-        'Template id: the id of one version of a template, as "frodo app template list" prints it (for example 1_2-saml). Ids are not case-sensitive.'
-      ).makeOptionMandatory()
+        'Template id: the id of the template, as "frodo app template list" prints it (for example azure.ad). Dots and hyphens are the same, and the case does not matter. Cannot be used with -n.'
+      ).conflicts(['templateName'])
+    )
+    .addOption(
+      new Option(
+        '-n, --template-name <template-name>',
+        'Display name of the template (for example "Microsoft Entra"), as "frodo app template list --long" prints it. The case does not matter. Cannot be used with -i.'
+      ).conflicts(['templateId'])
+    )
+    .addOption(
+      new Option(
+        '-v, --template-version <version>',
+        'The version to describe (for example 3.1). Default: the newest version. The versions of a template are listed in its description.'
+      )
+    )
+    .addOption(
+      new Option(
+        '-l, --long',
+        'Long: also the properties of each object type and the fields of the connector configuration and of the application form.'
+      ).default(false, 'false')
     )
     .addOption(
       new Option(
@@ -40,16 +59,32 @@ export default function setup() {
     )
     .addOption(templatesOption())
     .addOption(channelOption())
+    .requireOneOf({
+      options: ['templateId', 'templateName'],
+      purpose: 'which template to describe',
+    })
     // without a tenant there is nothing to connect to: the catalog is public
     .skipConnectionPromptsWhen(
       (command) => !positionalValue(command, 'host') && !state.getHost()
     )
     .addHelpText(
       'after',
-      `Without a tenant the command reads the catalog alone and needs no login. With a tenant it also finds the templates the tenant defines itself.\n\n` +
+      `Without a tenant the command reads the catalog alone and needs no login. With a tenant it also finds the templates the tenant defines itself. A template has several versions; the description of the newest lists the others, and -v describes one of them.\n\n` +
         `Usage Examples:\n` +
-        `  Describe the template '${s.appTemplateId}' of the catalog, without a tenant:\n` +
+        `  Describe the newest version of the template '${s.appTemplateId}' of the catalog, without a tenant:\n` +
         c.command(`  $ frodo app template describe -i ${s.appTemplateId}\n`) +
+        `  Describe another version of it:\n` +
+        c.command(
+          `  $ frodo app template describe -i ${s.appTemplateId} -v ${s.appTemplateVersion}\n`
+        ) +
+        `  Name the template by its display name:\n` +
+        c.command(
+          `  $ frodo app template describe -n "${s.appTemplateName}"\n`
+        ) +
+        `  Add the properties of the object types and the fields of the forms:\n` +
+        c.command(
+          `  $ frodo app template describe -i ${s.appTemplateId} --long\n`
+        ) +
         `  Print the whole template in JSON format:\n` +
         c.command(
           `  $ frodo app template describe -i ${s.appTemplateId} --json\n`
@@ -79,26 +114,26 @@ export default function setup() {
           command
         );
         const withTenant = !!state.getHost();
-        // an unspecified -i gets a picker from the framework after the login
-        // (decision record 0038), so the login comes first
+        // an unspecified -i/-n gets a picker from the framework after the
+        // login (decision record 0038), so the login comes first
         if (withTenant && !(await getTokens(false, true, deploymentTypes))) {
           process.exitCode = 1;
           return;
         }
-        if (!options.templateId) {
-          printMessage(
-            `Error: -i, --template-id is required. "frodo app template list" prints the ids.`,
-            'error'
-          );
-          process.exitCode = 1;
-          return;
-        }
-        const outcome = await describeApplicationTemplate(options.templateId, {
-          templates: options.templates,
-          channel: options.channel,
-          json: options.json,
-          includeOverrides: withTenant,
-        });
+        const outcome = await describeApplicationTemplate(
+          {
+            id: options.templateId,
+            name: options.templateName,
+            version: options.templateVersion,
+          },
+          {
+            templates: options.templates,
+            channel: options.channel,
+            json: options.json,
+            long: options.long,
+            includeOverrides: withTenant,
+          }
+        );
         if (!outcome) process.exitCode = 1;
       }
       // end command logic inside action handler

src/cli/app/app-template-list.ts

@@ -26,10 +26,19 @@ export default function setup() {
 
   program
     .description(
-      'List application templates: the catalog of the Admin UI, with the templates of the tenant merged over it when a tenant is given.'
+      'List application templates, one per template with its newest version: the catalog of the Admin UI, with the templates of the tenant merged over it when a tenant is given.'
     )
     .addOption(
-      new Option('-l, --long', 'Long with all fields.').default(false, 'false')
+      new Option(
+        '-l, --long',
+        'Long: a table with the display name, category, what the template provides, its connector, its newest version, the number of versions and the date of the newest.'
+      ).default(false, 'false')
+    )
+    .addOption(
+      new Option(
+        '--all-versions',
+        'List every version of every template, not only the newest: the id and the version.'
+      ).default(false, 'false')
     )
     .addOption(templatesOption())
     .addOption(channelOption())
@@ -39,12 +48,14 @@ export default function setup() {
     )
     .addHelpText(
       'after',
-      `Without a tenant the command lists the catalog alone and needs no login. With a tenant (AM base URL, connection profile or alias) it logs in and merges the templates the tenant defines itself, marked as overrides.\n\n` +
+      `Without a tenant the command lists the catalog alone and needs no login. With a tenant (AM base URL, connection profile or alias) it logs in and merges the templates the tenant defines itself, marked as overrides. "frodo app template describe" takes an id as printed here and describes the newest version of the template, or the one that -v names.\n\n` +
         `Usage Examples:\n` +
         `  List the ids of the templates of the catalog, without a tenant:\n` +
         c.command(`  $ frodo app template list\n`) +
-        `  List them with all fields:\n` +
+        `  List them with the display name, category, connector and newest version:\n` +
         c.command(`  $ frodo app template list --long\n`) +
+        `  List every version of every template:\n` +
+        c.command(`  $ frodo app template list --all-versions\n`) +
         `  List the catalog and the templates of a tenant, using AM base URL, realm, username and password:\n` +
         c.command(
           `  $ frodo app template list --long ${s.amBaseUrl} ${s.realm} ${s.username} '${s.password}'\n`
@@ -77,6 +88,7 @@ export default function setup() {
           templates: options.templates,
           channel: options.channel,
           long: options.long,
+          allVersions: options.allVersions,
           includeOverrides: withTenant,
         });
         if (!outcome) process.exitCode = 1;

src/help/SampleData.ts

@@ -59,5 +59,7 @@ export const aiAgentId = 'oracle-assistant';
 export const aiAgentFile = 'oracle-assistant.ai.agent.json';
 export const allAiAgentsFile = 'allAlphaAIAgents.ai.agent.json';
 export const logApiKeyId = 'e4b1d9f2-6a3c-4d57-9b0e-2f8a6c1d7e35';
-export const appTemplateId = '1_2-saml';
+export const appTemplateId = 'azure.ad';
+export const appTemplateName = 'Microsoft Entra';
+export const appTemplateVersion = '3.1';
 export const appTemplatesFile = 'appTemplates.json';