feat: enhance lifecycle command execution with improved argument handling

- Updated the LifecycleExecuteCommand to require a source argument with a flag for better CLI usability.
- Introduced a new function to build console command previews, improving command generation for cron tasks.
- Enhanced the lifecycle hooks service to validate cron rules before execution, returning execution status.
- Updated the configuration DTO to include the rule file basename for better rule management.
- Improved tests to cover new argument handling and command preview functionality.

Author: tacxou

apps/api/src/_common/decorators/cron-console-handler.decorator.ts

@@ -5,13 +5,15 @@ export const CRON_CONSOLE_HANDLER_METADATA = 'sesame:cron-console-handler'
 export type CronConsoleHandlerArgumentType = 'string' | 'number' | 'boolean'
 
 export interface CronConsoleHandlerArgument {
-  /** Nom de l'argument (`limit` → `--limit`, ou argument positionnel si `positional: true`). */
+  /** Nom de l'argument dans options cron / options CLI. */
   name: string
   label?: string
   description?: string
   type?: CronConsoleHandlerArgumentType
   default?: string | number | boolean
   required?: boolean
+  /** Flag CLI (ex. `--source`). Par défaut : `--${name}`. */
+  flag?: string
   /** Passe la valeur comme argument positionnel après la commande console. */
   positional?: boolean
 }

apps/api/src/core/cron/_functions/cron-command-options.function.ts

@@ -8,6 +8,24 @@ function getHandlerDescriptor(handler: string) {
   return getCronConsoleHandlers().find((entry) => entry.handler === handler)
 }
 
+export function resolveCronConsoleArgumentFlag(argument: CronConsoleHandlerArgument): string {
+  return argument.flag || `--${argument.name}`
+}
+
+export function buildConsoleCommandPreview(
+  handler: string,
+  options?: Record<string, unknown> | null,
+): string {
+  const descriptor = getHandlerDescriptor(handler)
+  if (!descriptor) {
+    return ''
+  }
+
+  const commandWords = descriptor.command.split(/\s+/).filter(Boolean)
+  const { positionalArgs, flagArgs } = buildCronCommandArgs(handler, options)
+  return ['yarn', 'run', 'console', ...commandWords, ...positionalArgs, ...flagArgs].join(' ')
+}
+
 function assertArgumentType(argument: CronConsoleHandlerArgument, value: unknown, handler: string): void {
   if (value === undefined || value === null || value === '') {
     return
@@ -107,9 +125,12 @@ export function buildCronCommandArgs(
     : Object.entries(options).filter(([key]) => !positionalSchema.some((argument) => argument.name === key))
 
   for (const [key, value] of flagEntries) {
+    const argument = flagSchema.find((entry) => entry.name === key)
+    const flag = argument ? resolveCronConsoleArgumentFlag(argument) : `--${key}`
+
     if (typeof value === 'boolean') {
       if (value) {
-        flagArgs.push(`--${key}`)
+        flagArgs.push(flag)
       }
       continue
     }
@@ -119,11 +140,11 @@ export function buildCronCommandArgs(
     }
 
     if (typeof value === 'object') {
-      flagArgs.push(`--${key}='${JSON.stringify(value)}'`)
+      flagArgs.push(`${flag}='${JSON.stringify(value)}'`)
       continue
     }
 
-    flagArgs.push(`--${key}='${String(value)}'`)
+    flagArgs.push(`${flag}='${String(value)}'`)
   }
 
   return { positionalArgs, flagArgs }

apps/api/src/management/lifecycle/_dto/config-rules.dto.ts

@@ -329,4 +329,9 @@ export class ConfigRulesObjectSchemaDTO {
   @ValidateNested({ each: true })
   @Type(() => ConfigRulesObjectIdentitiesDTO)
   public identities: ConfigRulesObjectIdentitiesDTO[]
+
+  /** Nom du fichier YAML sans extension (ex. `01-etd`). Renseigné au chargement. */
+  @IsOptional()
+  @IsString()
+  public ruleFileBasename?: string
 }

apps/api/src/management/lifecycle/_functions/load-lifecycle-rules.function.ts

@@ -119,6 +119,7 @@ export async function loadLifecycleRules(): Promise<ConfigRulesObjectSchemaDTO[]
     }
 
     lifecycleRules.push(schema)
+    schema.ruleFileBasename = file.replace(/\.(ya?ml)$/i, '')
     logger.debug(`Lifecycle activated from file: ${file}`)
   }
 

apps/api/src/management/lifecycle/_functions/validate-lifecycle-cron-rules.function.ts

@@ -0,0 +1,44 @@
+import { ConfigRulesObjectIdentitiesDTO } from '../_dto/config-rules.dto'
+
+export interface LifecycleCronRulesValidationResult {
+  executable: boolean
+  rules: ConfigRulesObjectIdentitiesDTO[]
+  warnings: string[]
+}
+
+export function validateLifecycleCronRules(
+  ruleFileBasename: string,
+  identities: ConfigRulesObjectIdentitiesDTO[] | undefined,
+): LifecycleCronRulesValidationResult {
+  if (!identities?.length) {
+    return {
+      executable: false,
+      rules: [],
+      warnings: [`Le fichier de règles <${ruleFileBasename}.yml> ne contient aucune règle.`],
+    }
+  }
+
+  const cronExecutableRules = identities.filter((rule) => rule.trigger === -1)
+  if (cronExecutableRules.length > 0) {
+    return {
+      executable: true,
+      rules: cronExecutableRules,
+      warnings: [],
+    }
+  }
+
+  const warnings = [
+    `Le fichier de règles <${ruleFileBasename}.yml> ne contient aucune règle exécutable en cron (trigger=-1 requis).`,
+  ]
+
+  for (const rule of identities) {
+    const triggerLabel = rule.trigger === undefined || rule.trigger === null ? 'non défini' : String(rule.trigger)
+    warnings.push(`  • sources [${rule.sources.join(', ')}] → trigger=${triggerLabel}`)
+  }
+
+  return {
+    executable: false,
+    rules: [],
+    warnings,
+  }
+}

apps/api/src/management/lifecycle/lifecycle-hooks.service.ts

@@ -10,6 +10,7 @@ import { AbstractLifecycleService } from './_abstracts/abstract.lifecycle.servic
 import { ConfigRulesObjectSchemaDTO } from './_dto/config-rules.dto'
 import { loadCustomStates } from './_functions/load-custom-states.function'
 import { loadLifecycleRules } from './_functions/load-lifecycle-rules.function'
+import { validateLifecycleCronRules } from './_functions/validate-lifecycle-cron-rules.function'
 import { resolveConfigVariables } from '~/_common/functions/resolve-config-variables.function'
 
 @Injectable()
@@ -214,21 +215,32 @@ export class LifecycleHooksService extends AbstractLifecycleService {
     }
   }
 
-  public async executeCronForSource(source: string): Promise<void> {
+  public async executeCronForSource(source: string): Promise<boolean> {
     this.logger.log(`Executing lifecycle rules for source <${source}>...`)
 
     const lifecycleRules = await this.ensureLifecycleCacheFresh()
+    const ruleSet = lifecycleRules.find((rules) => rules.ruleFileBasename === source)
 
-    for (const lfr of lifecycleRules) {
-      for (const idRule of lfr.identities) {
-        console.log('Checking identity rule sources:', idRule)
-        if (idRule.sources.includes(source as any) && idRule.trigger === -1) {
-          await this.handleCron({ lifecycleRules: [lfr], ignoreTrigger: true })
-        }
-      }
+    if (!ruleSet) {
+      this.logger.warn(`Fichier de règles lifecycle introuvable pour <${source}> (configs/lifecycle/rules/${source}.yml).`)
+      return false
     }
 
-    this.logger.log(`Execution of lifecycle rules for source <${source}> completed.`)
+    const validation = validateLifecycleCronRules(source, ruleSet.identities)
+    if (validation.executable) {
+      await this.handleCron({
+        lifecycleRules: [{ ...ruleSet, identities: validation.rules }],
+        ignoreTrigger: true,
+      })
+
+      this.logger.log(`Execution of lifecycle rules for source <${source}> completed.`)
+      return true
+    }
+
+    for (const warning of validation.warnings) {
+      this.logger.warn(warning)
+    }
+    return false
   }
 
   public async executeCronForAllSources(): Promise<void> {

apps/api/src/management/lifecycle/lifecycle.command.ts

@@ -1,6 +1,6 @@
 import { Logger } from '@nestjs/common'
 import { ModuleRef } from '@nestjs/core'
-import { Command, CommandRunner, InquirerService, SubCommand } from 'nest-commander'
+import { Command, CommandRunner, InquirerService, Option, SubCommand } from 'nest-commander'
 import { CronConsoleHandler } from '~/_common/decorators/cron-console-handler.decorator'
 import { LifecycleCrudService } from './lifecycle-crud.service'
 import { LifecycleHooksService } from './lifecycle-hooks.service'
@@ -83,9 +83,10 @@ export class LifecycleListCommand extends CommandRunner {
     {
       name: 'source',
       label: 'Source lifecycle',
-      description: 'Identifiant de source (ex. 01-etd). Laisser vide pour exécuter toutes les sources.',
+      description: 'Nom du fichier de règles sans extension (ex. 01-etd → configs/lifecycle/rules/01-etd.yml).',
       type: 'string',
-      positional: true,
+      flag: '--source',
+      required: true,
     },
   ],
 })
@@ -102,29 +103,39 @@ export class LifecycleExecuteCommand extends CommandRunner {
     super()
   }
 
-  async run(inputs: string[], options: any): Promise<void> {
+  async run(_inputs: string[], options: LifecycleExecuteOptions): Promise<void> {
     this.logger.log('Démarrage de la commande d\'exécution du cycle de vie...')
 
-    const source = inputs[0]
+    const source = `${options?.source || ''}`.trim()
     if (!source) {
-      this.logger.log('Aucune source de cycle de vie spécifiée. Exécution pour toutes les sources...')
-
-      try {
-        await this.lifecycleHooksService.executeCronForAllSources()
-        this.logger.log(`Exécution du cycle de vie pour toutes les sources terminée avec succès.`)
-      } catch (error) {
-        this.logger.error(`Erreur lors de l'exécution du cycle de vie pour toutes les sources: ${error.message}`)
-      }
+      console.error('Usage: yarn run console lifecycle execute --source=<source>')
       return
     }
 
     try {
-      await this.lifecycleHooksService.executeCronForSource(source)
+      const executed = await this.lifecycleHooksService.executeCronForSource(source)
+      if (!executed) {
+        process.exitCode = 1
+        return
+      }
       this.logger.log(`Exécution du cycle de vie pour la source '${source}' terminée avec succès.`)
     } catch (error) {
       this.logger.error(`Erreur lors de l'exécution du cycle de vie pour la source '${source}': ${error.message}`)
     }
   }
+
+  @Option({
+    flags: '--source <source>',
+    description: 'Nom du fichier de règles lifecycle sans extension (ex. 01-etd).',
+    required: true,
+  })
+  parseSource(val: string): string {
+    return `${val || ''}`.trim()
+  }
+}
+
+type LifecycleExecuteOptions = {
+  source: string
 }
 
 /**
@@ -144,7 +155,7 @@ export class LifecycleExecuteCommand extends CommandRunner {
  * @example
  * // Utilisation en ligne de commande
  * yarn run console lifecycle list
- * yarn run console lifecycle <autre-sous-commande>
+ * yarn run console lifecycle execute --source=01-etd
  */
 @Command({ name: 'lifecycle', arguments: '<task>', subCommands: [LifecycleListCommand, LifecycleExecuteCommand] })
 export class LifecycleCommand extends CommandRunner {

apps/api/tests/unit/core/cron/cron-command-options.function.spec.ts

@@ -1,5 +1,6 @@
 import { BadRequestException } from '@nestjs/common'
 import {
+  buildConsoleCommandPreview,
   buildCronCommandArgs,
   validateCronTaskOptions,
 } from '~/core/cron/_functions/cron-command-options.function'
@@ -19,7 +20,7 @@ jest.mock('~/_common/decorators/cron-console-handler.decorator', () => ({
       command: 'lifecycle execute',
       label: 'Exécution du cycle de vie',
       arguments: [
-        { name: 'source', type: 'string', positional: true },
+        { name: 'source', type: 'string', flag: '--source', required: true },
       ],
     },
     {
@@ -45,15 +46,28 @@ describe('cron-command-options', () => {
     expect(() => validateCronTaskOptions('agents-list', { limit: 500 })).toThrow(BadRequestException)
   })
 
+  it('should reject missing required options', () => {
+    expect(() => validateCronTaskOptions('lifecycle-execute', {})).toThrow(BadRequestException)
+  })
+
   it('should build flag and positional CLI args from handler schema', () => {
     expect(buildCronCommandArgs('identities-pwned-recheck', { limit: 500 })).toEqual({
       positionalArgs: [],
       flagArgs: ["--limit='500'"],
     })
 
     expect(buildCronCommandArgs('lifecycle-execute', { source: '01-etd' })).toEqual({
-      positionalArgs: ['01-etd'],
-      flagArgs: [],
+      positionalArgs: [],
+      flagArgs: ["--source='01-etd'"],
     })
   })
+
+  it('should build console command preview from handler command and flags', () => {
+    expect(buildConsoleCommandPreview('lifecycle-execute', { source: '01-etd' })).toBe(
+      "yarn run console lifecycle execute --source='01-etd'",
+    )
+    expect(buildConsoleCommandPreview('identities-pwned-recheck', { limit: 1 })).toBe(
+      "yarn run console identities pwned recheck --limit='1'",
+    )
+  })
 })

apps/api/tests/unit/management/lifecycle/validate-lifecycle-cron-rules.function.spec.ts

@@ -0,0 +1,42 @@
+import { validateLifecycleCronRules } from '~/management/lifecycle/_functions/validate-lifecycle-cron-rules.function'
+
+describe('validateLifecycleCronRules', () => {
+  it('should accept rules with trigger=-1', () => {
+    const result = validateLifecycleCronRules('01-etd', [
+      {
+        sources: ['D'],
+        trigger: -1,
+        target: 'I',
+      } as any,
+    ])
+
+    expect(result.executable).toBe(true)
+    if (result.executable) {
+      expect(result.rules).toHaveLength(1)
+    }
+  })
+
+  it('should reject rules without trigger=-1', () => {
+    const result = validateLifecycleCronRules('01-etd', [
+      {
+        sources: ['I', 'W'],
+        trigger: 5,
+        target: 'D',
+      } as any,
+      {
+        sources: ['D'],
+        target: 'I',
+      } as any,
+    ])
+
+    expect(result).toEqual({
+      executable: false,
+      rules: [],
+      warnings: [
+        'Le fichier de règles <01-etd.yml> ne contient aucune règle exécutable en cron (trigger=-1 requis).',
+        '  • sources [I, W] → trigger=5',
+        '  • sources [D] → trigger=non défini',
+      ],
+    })
+  })
+})