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

/**
 * Énumération des modes d'exécution.
 * - interactive : Mode React/Ink UI (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 des commandes, utilisée pour le regroupement de l'aide,
 * le badge de complétion, les commandes disponibles ACP.
 *
 * Différence avec CommandKind :
 * - CommandKind est une classification interne du chargeur (4 types), affecte la logique de chargement
 * - CommandSource est une classification orientée utilisateur (9 types), affecte l'affichage et le modèle mental
 *
 * Ils peuvent se chevaucher, mais ont des responsabilités différentes, ne pas fusionner.
 */
export type CommandSource =
  | 'builtin-command' // Commande intégrée (BuiltinCommandLoader)
  | 'bundled-skill' // Skill distribué avec le package (BundledSkillLoader)
  | 'skill-dir-command' // Commande fichier depuis .qwen/commands/ utilisateur/projet (FileCommandLoader, non plugin)
  | 'plugin-command' // Commande fournie par un plugin (FileCommandLoader, extensionName non vide)
  | 'mcp-prompt'; // Prompt fourni par un serveur MCP (McpPromptLoader)
// Sources suivantes réservées, Phase 1 n'implémente pas de chargeur correspondant, mais le schéma est défini à l'avance :
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * Type d'exécution de la commande, décrit "comment la commande s'exécute".
 *
 * - prompt : produit un submit_prompt, soumet le contenu au modèle. Convient pour skill, file command, MCP prompt.
 *   Modes par défaut supportedModes : tous les modes, modelInvocable par défaut : true.
 *
 * - local : exécute une logique localement, ne dépend pas de React/Ink UI. Peut retourner message, stream_messages,
 *   submit_prompt, tool, etc. Convient pour les commandes built-in de requête, configuration, état.
 *   Modes par défaut supportedModes : ['interactive'], nécessite une déclaration explicite de supportedModes pour être ouverte aux autres modes.
 *   Cela correspond à la sémantique de supportsNonInteractive: true de Claude Code — le support non interactif nécessite une déclaration explicite, pas une inférence automatique.
 *
 * - local-jsx : commande qui dépend de React/Ink UI (ouvrir un dialog, rendre des composants JSX, etc.).
 *   Modes par défaut supportedModes : uniquement ['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[];
 
  // ── Nouveautés Phase 1 : source et type d'exécution ──────────────────────────────────────
  /**
   * Source de la commande, utilisée pour le regroupement de l'aide, le badge de complétion,
   * l'affichage des commandes disponibles ACP.
   * Rempli par chaque chargeur, pas déclaré par la commande elle-même.
   * Lorsque CommandKind sera abandonné, source deviendra l'identifiant unique de source.
   */
  source?: CommandSource;
 
  /**
   * Étiquette de source destinée à l'utilisateur.
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * Rempli par chaque chargeur, peut être surchargé par la commande elle-même.
   */
  sourceLabel?: string;
 
  /**
   * Type d'exécution de la commande.
   * - Les chargeurs remplissent une valeur par défaut (prompt/local-jsx)
   * - Les commandes built-in sont déclarées par chaque fichier de commande (local ou local-jsx)
   * La stratégie par défaut en l'absence de déclaration est décrite dans getEffectiveCommandType().
   */
  commandType?: CommandType;
 
  // ── Nouveautés Phase 1 : capacités de mode ──────────────────────────────────────────
  /**
   * Modes d'exécution dans lesquels cette commande est disponible.
   * En l'absence de déclaration, la valeur par défaut est déduite en fonction de commandType
   * (voir getEffectiveSupportedModes()).
   * La déclaration explicite prime sur la valeur déduite.
   */
  supportedModes?: ExecutionMode[];
 
  // ── Nouveautés Phase 1 : visibilité ──────────────────────────────────────────────
  /**
   * L'utilisateur peut-il invoquer cette commande via un slash command ?
   * Par défaut true (presque toutes les commandes sont userInvocable).
   */
  userInvocable?: boolean;
 
  /**
   * Le modèle peut-il invoquer cette commande via un tool call ?
   * Par défaut false. Les commandes de type prompt (skill, file command, MCP prompt) doivent être mises à true.
   * Les commandes built-in ne sont pas autorisées à être invoquées par le modèle (toujours false).
   */
  modelInvocable?: boolean;
 
  // ── Réservé Phase 3 : métadonnées d'expérience (Phase 1 définit seulement, n'utilise pas)──────────────────
  /**
   * Indice d'argument, affiché 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;
 
  /**
   * Explication à destination du modèle pour savoir quand invoquer cette commande.
   * Sera injectée dans la description des commandes modelInvocable.
   */
  whenToUse?: string;
 
  /**
   * Exemples d'utilisation, pour l'affichage dans l'aide et la complétion.
   */
  examples?: string[];
}

// Ne remplit pas source/sourceLabel/commandType — déclaré par chaque fichier de commande
// car le commandType des commandes built-in est local ou local-jsx, nécessite un marquage individuel
 
// Injecte 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 autorisées à être invoquées 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éterminée selon 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 autorisées pour le moment, les commandes utilisateur/projet oui
  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
};

/**
 * Obtient la liste réelle des modes supportés par une commande.
 *
 * Priorité d'inférence (de la plus haute à la plus basse) :
 * 1. supportedModes déclaré explicitement par la commande (priorité la plus haute)
 * 2. Inférence basée sur commandType
 * 3. Repli basé sur CommandKind (rétrocompatibilité)
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // Priorité 1 : déclaration explicite
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // Priorité 2 : inférence basée sur commandType
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // Les commandes de type prompt n'ont pas de dépendance UI, disponibles dans tous les modes par nature
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // Par défaut conservateur pour le type local : seulement interactive.
        // Les commandes nécessitant un support non interactif doivent déclarer explicitement supportedModes
        // (correspond à supportsNonInteractive: true de Claude Code).
        // Phase 2 les validera une par une et les débloquera, pour éviter qu'une commande non adaptée
        // ne soit exposée accidentellement à un appelant headless.
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // Priorité 3 : repli (basé sur CommandKind, rétrocompatibilité avec l'ancien code)
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // Commandes built-in sans commandType déclaré : par défaut conservateur (interactive only)
      // Cette branche ne devrait plus être atteinte après la fin de 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 par nature,
      // et le comportement historique était qu'elles sont disponibles dans tous les modes
      return ['interactive', 'non_interactive', 'acp'];
    default:
      return ['interactive'];
  }
}

/**
 * Filtre les commandes adaptées au mode actuel selon 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 dans le mode d'exécution spécifié.
   * Remplace l'ancienne combinaison de liste blanche + filterCommandsForNonInteractive.
   *
   * @param mode Mode d'exécution cible
   * @returns Commandes adaptées à ce mode (sans les commandes cachées)
   */
  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 ; Phase 1 ne fournit que l'interface.
   *
   * @returns Commandes invocables 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[] { ... }

// ✅ À ajouter (ou importer 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,
  // pas de transmission, utilise la liste blanche par défaut
);
 
// ✅ Nouvel appel (pas de changement, le paramètre par défaut qui n'existe plus est supprimé)
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, seulement interactive
export const modelCommandInteractive: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local-jsx',
  supportedModes: ['interactive'], // limitation explicite
  // action: ouvre une boîte de dialogue 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, renvoie un message (texte brut)
};

describe('getEffectiveSupportedModes', () => {
  it('supportedModes explicite prime sur l’inférence de commandType', () => {
    const cmd: SlashCommand = {
      name: 'test', description: '', kind: CommandKind.BUILT_IN,
      commandType: 'local',
      supportedModes: ['interactive'], // restriction explicite
    };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: local infère 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 infère interactive seulement', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local-jsx' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: prompt infère 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 à 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 à 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 à tous les modes (correction de la limitation précédente)', () => {
    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 cachées (filterCommandsForMode ne traite pas hidden, c’est CommandService qui le fait)', () => { ... });
});