Document de conception technique Phase 1 : Reconstruction de l’infrastructure

/**
 * Énumération des modes d'exécution.
 * - interactive : mode UI React/Ink (interaction terminal)
 * - non_interactive : mode CLI sans interaction (sortie texte/JSON)
 * - acp : mode d'intégration ACP/Zed
 */
export type ExecutionMode = 'interactive' | 'non_interactive' | 'acp';

/**
 * Énumération de la source de la commande, utilisée pour le regroupement dans l'aide, les badges de complétion et les commandes disponibles ACP.
 *
 * Différence avec CommandKind :
 * - CommandKind est une classification interne du chargeur (4 types), qui affecte la logique de chargement
 * - CommandSource est une classification de source orientée utilisateur (9 types), qui affecte l'affichage et le modèle mental
 *
 * Les deux peuvent se chevaucher, mais leurs responsabilités diffèrent, ils ne sont pas fusionnés.
 */
export type CommandSource =
  | 'builtin-command' // Commandes intégrées (BuiltinCommandLoader)
  | 'bundled-skill' // Skills distribués avec le package (BundledSkillLoader)
  | 'skill-dir-command' // Commandes fichier sous .qwen/commands/ utilisateur/projet (FileCommandLoader, non plugin)
  | 'plugin-command' // Commandes fournies par un plugin (FileCommandLoader, extensionName non vide)
  | 'mcp-prompt'; // Prompts fournis par un serveur MCP (McpPromptLoader)
// Sources réservées pour plus tard, non implémentées en Phase 1, mais définies dans le schéma :
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * Type d'exécution de la commande, décrivant "comment" la commande s'exécute.
 *
 * - prompt : génère un submit_prompt, soumet le contenu au modèle. S'applique aux skills, file commands, prompts MCP.
 *   supportedModes par défaut : tous les modes, modelInvocable par défaut : true.
 *
 * - local : exécution logique locale, ne dépend pas de l'UI React/Ink. Peut retourner message, stream_messages,
 *   submit_prompt, tool, etc. S'applique aux commandes built-in de type requête, configuration, état.
 *   supportedModes par défaut : ['interactive'], nécessite une déclaration explicite de supportedModes pour être exposé aux autres modes.
 *   Cela correspond à la sémantique de supportsNonInteractive: true dans Claude Code : le support non interactif doit être déclaré explicitement, et non déduit automatiquement.
 *
 * - local-jsx : commandes dépendant de l'UI React/Ink (ouverture de dialog, rendu de composants JSX, etc.).
 *   supportedModes par défaut : ['interactive'].
 */
export type CommandType = 'prompt' | 'local' | 'local-jsx';

export interface SlashCommand {
  // ── Champs existants (inchangés) ──────────────────────────────────────────────
  name: string;
  altNames?: string[];
  description: string;
  hidden?: boolean;
  completionPriority?: number;
  kind: CommandKind;
  extensionName?: string;
  action?: (...) => ...;
  completion?: (...) => ...;
  subCommands?: SlashCommand[];
 
  // ── Nouveaux Phase 1 : Source et type d'exécution ──────────────────────────────────────
  /**
   * Source de la commande, utilisée pour le regroupement dans l'aide, les badges de complétion et l'affichage des commandes disponibles ACP.
   * Remplie par chaque Loader, non déclarée par la commande elle-même.
   * Lors de la future dépréciation de CommandKind, source deviendra l'unique identifiant de source.
   */
  source?: CommandSource;
 
  /**
   * Étiquette de source pour l'affichage, orientée utilisateur.
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * Remplie par chaque Loader, peut être surchargée par la commande elle-même.
   */
  sourceLabel?: string;
 
  /**
   * Type d'exécution de la commande.
   * - Valeur par défaut remplie par les Loaders (prompt/local-jsx)
   * - Déclarée par les fichiers de commandes built-in eux-mêmes (local ou local-jsx)
   * Voir getEffectiveCommandType() pour la stratégie par défaut en cas d'absence de déclaration.
   */
  commandType?: CommandType;
 
  // ── Nouveaux Phase 1 : Capacités de mode ──────────────────────────────────────────
  /**
   * Modes d'exécution dans lesquels cette commande est disponible.
   * Valeur par défaut déduite de commandType si non déclarée (voir getEffectiveSupportedModes()).
   * Une déclaration explicite prime sur la valeur déduite.
   */
  supportedModes?: ExecutionMode[];
 
  // ── Nouveaux Phase 1 : Visibilité ──────────────────────────────────────────────
  /**
   * Indique si l'utilisateur peut appeler cette commande via une slash command.
   * Par défaut true (presque toutes les commandes sont userInvocable).
   */
  userInvocable?: boolean;
 
  /**
   * Indique si le modèle peut appeler cette commande via un tool call.
   * Par défaut false. Les commandes de type prompt (skill, file command, prompt MCP) doivent être définies sur true.
   * Les commandes built-in ne sont pas appelables par le modèle (toujours false).
   */
  modelInvocable?: boolean;
 
  // ── Réservé Phase 3 : Métadonnées d'expérience (défini en Phase 1, non utilisé) ──────────────────
  /**
   * Indication des paramètres, affichée après le nom de la commande dans le menu de complétion.
   * Exemple : "<model-id>" / "show|list|set <id>" / "[--fast] [<model-id>]"
   */
  argumentHint?: string;
 
  /**
   * Description pour aider le modèle à comprendre quand appeler cette commande.
   * Sera injectée dans la description des commandes modelInvocable.
   */
  whenToUse?: string;
 
  /**
   * Exemples d'utilisation, pour la documentation d'aide et l'affichage de complétion.
   */
  examples?: string[];
}

// Ne pas remplir source/sourceLabel/commandType — déclarés par chaque fichier de commande
// car le commandType des commandes built-in est local ou local-jsx, nécessitant une annotation individuelle
 
// Injection de source et sourceLabel :
for (const cmd of rawCommands) {
  enrichedCommands.push({
    ...cmd,
    source: 'builtin-command',
    sourceLabel: 'Built-in',
    userInvocable: cmd.userInvocable ?? true,
    modelInvocable: false, // Les commandes built-in ne sont pas appelables par le modèle
  });
}

return skills.map((skill) => ({
  name: skill.name,
  description: skill.description,
  kind: CommandKind.SKILL,
  source: 'bundled-skill' as CommandSource,
  sourceLabel: 'Skill',
  commandType: 'prompt' as CommandType,
  userInvocable: true,
  modelInvocable: true,
  action: async (...) => { ... },
}));

// Dans createSlashCommandFromDefinition :
return {
  name: baseCommandName,
  description,
  kind: CommandKind.FILE,
  extensionName,
  // source dépend de extensionName :
  source: extensionName ? 'plugin-command' : 'skill-dir-command',
  sourceLabel: extensionName ? `Plugin: ${extensionName}` : 'Custom',
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: !extensionName, // Les commandes plugin ne sont pas encore appelables par le modèle pour des raisons de sécurité, les commandes utilisateur/projet le sont
  action: async (...) => { ... },
};

const newPromptCommand: SlashCommand = {
  name: commandName,
  description: prompt.description || `Invoke prompt ${prompt.name}`,
  kind: CommandKind.MCP_PROMPT,
  source: 'mcp-prompt',
  sourceLabel: `MCP: ${serverName}`,
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: true,
  // ... autres champs existants
};

/**
 * Récupère la liste des modes réellement supportés par la commande.
 *
 * Priorité de déduction (du plus élevé au plus bas) :
 * 1. supportedModes déclaré explicitement par la commande (priorité maximale)
 * 2. Déduction basée sur commandType
 * 3. Fallback basé sur CommandKind (compatibilité descendante)
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // Priorité 1 : Déclaration explicite
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // Priorité 2 : Déduction basée sur commandType
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // Le type prompt n'a pas de dépendance UI, disponible nativement dans tous les modes
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // Type local par défaut conservateur : uniquement interactive.
        // Les commandes nécessitant un support non interactif doivent déclarer explicitement supportedModes (équivalent à supportsNonInteractive: true dans Claude Code).
        // Vérification et déblocage progressif en Phase 2 pour éviter d'exposer accidentellement des commandes non adaptées aux appelants headless.
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // Priorité 3 : Fallback (basé sur CommandKind, compatibilité descendante avec l'ancien code)
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // Commandes built-in sans commandType déclaré : par défaut conservateur (interactive uniquement)
      // Cette branche ne devrait plus être atteinte après la Phase 1 (toutes les built-in auront un commandType)
      return ['interactive'];
    case CommandKind.FILE:
    case CommandKind.SKILL:
    case CommandKind.MCP_PROMPT:
      // L'action de ces trois types de commandes n'a pas de dépendance UI, comportement historique : disponible dans tous les modes
      return ['interactive', 'non_interactive', 'acp'];
    default:
      return ['interactive'];
  }
}

/**
 * Filtre les commandes adaptées au mode actuel en fonction de supportedModes.
 * Remplace l'ancienne fonction filterCommandsForNonInteractive.
 */
export function filterCommandsForMode(
  commands: readonly SlashCommand[],
  mode: ExecutionMode,
): SlashCommand[] {
  return commands.filter((cmd) =>
    getEffectiveSupportedModes(cmd).includes(mode),
  );
}

export class CommandService {
  // ── Méthodes existantes (inchangées) ────────────────────────────────────────────────
  getCommands(): readonly SlashCommand[] {
    return this.commands;
  }
 
  // ── Nouvelles méthodes Phase 1 ──────────────────────────────────────────────────────
 
  /**
   * Retourne la liste des commandes disponibles pour un mode d'exécution donné.
   * Remplace la combinaison ancienne liste blanche + filterCommandsForNonInteractive.
   *
   * @param mode Mode d'exécution cible
   * @returns Liste des commandes adaptées à ce mode (exclut les commandes hidden)
   */
  getCommandsForMode(mode: ExecutionMode): readonly SlashCommand[] {
    return this.commands.filter((cmd) => {
      if (cmd.hidden) return false;
      return getEffectiveSupportedModes(cmd).includes(mode);
    });
  }
 
  /**
   * Retourne toutes les commandes dont modelInvocable est true.
   * SkillTool consommera cette méthode en Phase 2 ; la Phase 1 fournit uniquement l'interface.
   *
   * @returns Liste des commandes appelables par le modèle
   */
  getModelInvocableCommands(): readonly SlashCommand[] {
    return this.commands.filter(
      (cmd) => !cmd.hidden && cmd.modelInvocable === true,
    );
  }
}

// ❌ Supprimer
export const ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE = [
  'init', 'summary', 'compress', 'btw', 'bug', 'context',
] as const;
 
// ❌ Supprimer
function filterCommandsForNonInteractive(
  commands: readonly SlashCommand[],
  allowedBuiltinCommandNames: Set<string>,
): SlashCommand[] { ... }

// ✅ Ajouté (ou importé depuis commandUtils)
import { filterCommandsForMode } from '../services/commandUtils.js';

// ❌ Ancienne signature
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<NonInteractiveSlashCommandResult>
 
// ✅ Nouvelle signature (suppression de allowedBuiltinCommandNames)
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
): Promise<NonInteractiveSlashCommandResult>

// Ancien :
const filteredCommands = filterCommandsForNonInteractive(
  allCommands,
  allowedBuiltinSet,
);
 
// Nouveau :
const executionMode = isAcpMode ? 'acp' : 'non_interactive';
const filteredCommands = filterCommandsForMode(allCommands, executionMode);

// ❌ Ancienne signature
export const getAvailableCommands = async (
  config: Config,
  abortSignal: AbortSignal,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<SlashCommand[]>
 
// ✅ Nouvelle signature
export const getAvailableCommands = async (
  config: Config,
  abortSignal: AbortSignal,
  mode: ExecutionMode = 'acp',
): Promise<SlashCommand[]>

// ❌ Ancien appel
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
  // Non transmis, utilise la liste blanche par défaut
);
 
// ✅ Nouvel appel (inchangé, suppression du paramètre par défaut qui n'existe plus)
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
);
 
// ─────────────────────────────────────────
 
// ❌ Ancien appel
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
);
 
// ✅ Nouvel appel (mode spécifié explicitement)
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
  'acp',
);

// ① Version interactive : local-jsx, uniquement interactive
export const modelCommandInteractive: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local-jsx',
  supportedModes: ['interactive'], // Limitation explicite
  // action : ouvre un dialog pour sélectionner le modèle
};
 
// ② Version non interactive/acp : local, explicitement ouverte aux appelants headless
export const modelCommandHeadless: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local',
  supportedModes: ['non_interactive', 'acp'], // Limitation explicite
  // action : lit/définit le modèle, retourne un message (texte brut)
};

describe('getEffectiveSupportedModes', () => {
  it('supportedModes explicite prime sur la déduction commandType', () => {
    const cmd: SlashCommand = {
      name: 'test', description: '', kind: CommandKind.BUILT_IN,
      commandType: 'local',
      supportedModes: ['interactive'], // Limitation explicite
    };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: local déduit pour tous les modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('commandType: local-jsx déduit pour interactive uniquement', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local-jsx' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: prompt déduit pour tous les modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.SKILL, commandType: 'prompt' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('commandType non déclaré et CommandKind.BUILT_IN, fallback sur interactive', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType non déclaré et CommandKind.FILE, fallback sur tous les modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.FILE };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('commandType non déclaré et CommandKind.MCP_PROMPT, fallback sur tous les modes (correction de l\'ancienne limitation)', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.MCP_PROMPT };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
});
 
describe('filterCommandsForMode', () => {
  it('filtre correctement les commandes en mode non_interactive', () => { ... });
  it('filtre correctement les commandes en mode acp', () => { ... });
  it('ne filtre pas les commandes hidden (filterCommandsForMode ne gère pas hidden, CommandService s\'en charge)', () => { ... });
});