Documento de Design Técnico da Fase 1: Reestruturação da Infraestrutura

/**
 * Enumeração dos modos de execução.
 * - interactive: modo React/Ink UI (interação no terminal)
 * - non_interactive: modo CLI sem interação (saída texto/JSON)
 * - acp: modo ACP/Zed integration
 */
export type ExecutionMode = 'interactive' | 'non_interactive' | 'acp';

/**
 * Enumeração da origem do comando, usada para agrupamento no Help,
 * badge de completação e comandos disponíveis no ACP.
 *
 * Diferença em relação ao CommandKind:
 * - CommandKind é uma classificação interna do carregador (4 tipos), afeta a lógica de carregamento
 * - CommandSource é uma classificação de origem voltada ao usuário (9 tipos), afeta a exibição e o modelo mental
 *
 * Ambos podem se sobrepor, mas têm responsabilidades diferentes; não são mesclados.
 */
export type CommandSource =
  | 'builtin-command' // Comandos internos (BuiltinCommandLoader)
  | 'bundled-skill' // Skills distribuídas com o pacote (BundledSkillLoader)
  | 'skill-dir-command' // Comandos de arquivo do usuário/projeto .qwen/commands/ (FileCommandLoader, não é plugin)
  | 'plugin-command' // Comandos fornecidos por plugins (FileCommandLoader, extensionName não vazio)
  | 'mcp-prompt'; // Prompts fornecidos por servidores MCP (McpPromptLoader)
// As seguintes origens estão reservadas; a Fase 1 não implementa Loaders correspondentes, mas o schema é definido antecipadamente:
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * Tipo de execução do comando, descreve "como o comando é executado".
 *
 * - prompt: produz submit_prompt, envia o conteúdo para o modelo. Aplicável a skills, file commands, MCP prompts.
 *   O padrão de supportedModes são todos os modos; o padrão de modelInvocable é true.
 *
 * - local: executa lógica localmente, sem depender de React/Ink UI. Pode retornar message, stream_messages,
 *   submit_prompt, tool, etc. Adequado para comandos internos de consulta, configuração, estado.
 *   O padrão de supportedModes é ['interactive']; é necessário declarar explicitamente supportedModes para liberar para outros modos.
 *   Isso é consistente com a semântica de supportsNonInteractive: true do Claude Code — o suporte a não interativo precisa ser declarado explicitamente, não inferido automaticamente.
 *
 * - local-jsx: comandos que dependem de React/Ink UI (abrir dialog, renderizar componentes JSX, etc.).
 *   O padrão de supportedModes é apenas ['interactive'].
 */
export type CommandType = 'prompt' | 'local' | 'local-jsx';

export interface SlashCommand {
  // ── Campos existentes (permanecem inalterados) ──────────────────────────────────────────────
  name: string;
  altNames?: string[];
  description: string;
  hidden?: boolean;
  completionPriority?: number;
  kind: CommandKind;
  extensionName?: string;
  action?: (...) => ...;
  completion?: (...) => ...;
  subCommands?: SlashCommand[];
 
  // ── Novos campos da Fase 1: origem e tipo de execução ──────────────────────────────────────
  /**
   * Origem do comando, usado para agrupamento no Help, badge de completação e exibição de comandos disponíveis no ACP.
   * Preenchido por cada Loader, não declarado pelo próprio comando.
   * Quando CommandKind for descontinuado no futuro, source será o único identificador de origem.
   */
  source?: CommandSource;
 
  /**
   * Rótulo de origem voltado ao usuário.
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * Preenchido por cada Loader, pode ser sobrescrito pelo próprio comando.
   */
  sourceLabel?: string;
 
  /**
   * Tipo de execução do comando.
   * - Preenchido por cada Loader com valor padrão (prompt/local-jsx)
   * - Comandos internos: declarado pelo próprio arquivo de comando (local ou local-jsx)
   * Estratégia padrão quando não declarado: veja getEffectiveCommandType().
   */
  commandType?: CommandType;
 
  // ── Novos campos da Fase 1: capacidade de modo ──────────────────────────────────────────
  /**
   * Em quais modos de execução este comando está disponível.
   * Quando não declarado, o valor padrão é inferido com base em commandType (veja getEffectiveSupportedModes()).
   * Declaração explícita tem prioridade sobre o valor inferido.
   */
  supportedModes?: ExecutionMode[];
 
  // ── Novos campos da Fase 1: visibilidade ──────────────────────────────────────────────
  /**
   * Se o usuário pode invocar este comando via slash command.
   * Padrão true (quase todos os comandos são userInvocable).
   */
  userInvocable?: boolean;
 
  /**
   * Se o modelo pode invocar este comando via tool call.
   * Padrão false. Comandos do tipo prompt (skill, file command, MCP prompt) devem ser marcados como true.
   * Comandos internos (built-in) não permitem invocação pelo modelo (sempre false).
   */
  modelInvocable?: boolean;
 
  // ── Reservado para Fase 3: metadados de experiência (Fase 1 apenas define, não usa)──────────────────
  /**
   * Dica de parâmetros, exibida no menu de completação após o nome do comando.
   * Exemplo: "<model-id>" / "show|list|set <id>" / "[--fast] [<model-id>]"
   */
  argumentHint?: string;
 
  /**
   * Instrução para o modelo entender quando invocar este comando.
   * Será injetada na descrição de comandos modelInvocable.
   */
  whenToUse?: string;
 
  /**
   * Exemplos de uso, para exibição no catálogo Help e na completação.
   */
  examples?: string[];
}

// Não preenche source/sourceLabel/commandType — cada arquivo de comando declara por conta própria
// Porque o commandType de comandos internos é local ou local-jsx, precisa ser anotado individualmente
 
// Injeta source e sourceLabel:
for (const cmd of rawCommands) {
  enrichedCommands.push({
    ...cmd,
    source: 'builtin-command',
    sourceLabel: 'Built-in',
    userInvocable: cmd.userInvocable ?? true,
    modelInvocable: false, // Comandos internos não permitem invocação pelo modelo
  });
}

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 (...) => { ... },
}));

// Em createSlashCommandFromDefinition:
return {
  name: baseCommandName,
  description,
  kind: CommandKind.FILE,
  extensionName,
  // source é determinado por extensionName:
  source: extensionName ? 'plugin-command' : 'skill-dir-command',
  sourceLabel: extensionName ? `Plugin: ${extensionName}` : 'Custom',
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: !extensionName, // Comandos de plugin temporariamente não permitem invocação pelo modelo; comandos do usuário/projeto permitem
  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,
  // ... demais campos existentes
};

/**
 * Obtém a lista real de modos suportados pelo comando.
 *
 * Prioridade de inferência (da maior para a menor):
 * 1. supportedModes declarados explicitamente pelo comando (maior prioridade)
 * 2. Inferência baseada em commandType
 * 3. Fallback baseado em CommandKind (compatibilidade retroativa)
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // Prioridade 1: declaração explícita
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // Prioridade 2: inferência baseada em commandType
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // Comandos do tipo prompt não têm dependência de UI, naturalmente disponíveis em todos os modos
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // Comandos do tipo local, padrão conservador: apenas interactive.
        // Comandos que precisam de suporte a não interativo devem declarar explicitamente supportedModes
        // (correspondente a supportsNonInteractive: true do Claude Code).
        // Na Fase 2, cada um será verificado e desbloqueado individualmente para evitar que comandos não adaptados
        // sejam expostos acidentalmente a chamadores headless.
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // Prioridade 3: fallback (baseado em CommandKind, compatibilidade retroativa com código antigo)
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // Comandos internos sem commandType declarado: padrão conservador (apenas interactive)
      // Este ramo não deve mais ser atingido após a conclusão da Fase 1 (todos os comandos internos terão commandType)
      return ['interactive'];
    case CommandKind.FILE:
    case CommandKind.SKILL:
    case CommandKind.MCP_PROMPT:
      // Esses três tipos de comando têm action naturalmente sem dependência de UI; comportamento histórico também é disponível em todos os modos
      return ['interactive', 'non_interactive', 'acp'];
    default:
      return ['interactive'];
  }
}

/**
 * Filtra comandos adequados para o modo atual com base em supportedModes.
 * Substitui a função original filterCommandsForNonInteractive.
 */
export function filterCommandsForMode(
  commands: readonly SlashCommand[],
  mode: ExecutionMode,
): SlashCommand[] {
  return commands.filter((cmd) =>
    getEffectiveSupportedModes(cmd).includes(mode),
  );
}

export class CommandService {
  // ── Método existente (permanece inalterado)────────────────────────────────────────────────
  getCommands(): readonly SlashCommand[] {
    return this.commands;
  }
 
  // ── Novos métodos da Fase 1 ──────────────────────────────────────────────────
 
  /**
   * Retorna a lista de comandos disponíveis no modo de execução especificado.
   * Substitui a combinação anterior de lista branca + filterCommandsForNonInteractive.
   *
   * @param mode Modo de execução alvo
   * @returns Lista de comandos adequados para aquele modo (excluindo comandos ocultos)
   */
  getCommandsForMode(mode: ExecutionMode): readonly SlashCommand[] {
    return this.commands.filter((cmd) => {
      if (cmd.hidden) return false;
      return getEffectiveSupportedModes(cmd).includes(mode);
    });
  }
 
  /**
   * Retorna todos os comandos com modelInvocable igual a true.
   * Na Fase 2, SkillTool consumirá este método; na Fase 1, apenas fornece a interface.
   *
   * @returns Lista de comandos que podem ser invocados pelo modelo
   */
  getModelInvocableCommands(): readonly SlashCommand[] {
    return this.commands.filter(
      (cmd) => !cmd.hidden && cmd.modelInvocable === true,
    );
  }
}

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

// ✅ Adicionar (ou importar de commandUtils)
import { filterCommandsForMode } from '../services/commandUtils.js';

// ❌ Assinatura antiga
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<NonInteractiveSlashCommandResult>
 
// ✅ Nova assinatura (removido allowedBuiltinCommandNames)
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
): Promise<NonInteractiveSlashCommandResult>

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

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

// ❌ Chamada antiga
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
  // Não passava, usava a lista branca padrão
);
 
// ✅ Nova chamada (sem alteração, parâmetro padrão removido)
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
);
 
// ─────────────────────────────────────────
 
// ❌ Chamada antiga
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
);
 
// ✅ Nova chamada (modo explicitamente especificado)
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
  'acp',
);

// ① 交互模式版：local-jsx，仅 interactive
export const modelCommandInteractive: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local-jsx',
  supportedModes: ['interactive'], // 显式限定
  // action: 打开 dialog 选择 model
};
 
// ② 非交互/acp 版：local，显式开放给 headless 调用者
export const modelCommandHeadless: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local',
  supportedModes: ['non_interactive', 'acp'], // 显式限定
  // action: 读取/设置 model，返回 message（纯文本）
};

describe('getEffectiveSupportedModes', () => {
  it('显式 supportedModes 优先于 commandType 推断', () => {
    const cmd: SlashCommand = {
      name: 'test', description: '', kind: CommandKind.BUILT_IN,
      commandType: 'local',
      supportedModes: ['interactive'], // 显式限制
    };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: local 推断为 all 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 推断为 interactive only', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local-jsx' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: prompt 推断为 all modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.SKILL, commandType: 'prompt' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('未声明 commandType 且 CommandKind.BUILT_IN，兜底为 interactive', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('未声明 commandType 且 CommandKind.FILE，兜底为 all modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.FILE };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('未声明 commandType 且 CommandKind.MCP_PROMPT，兜底为 all modes（修复原有限制）', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.MCP_PROMPT };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
});
 
describe('filterCommandsForMode', () => {
  it('正确过滤 non_interactive 模式下的命令', () => { ... });
  it('正确过滤 acp 模式下的命令', () => { ... });
  it('不过滤 hidden 命令（filterCommandsForMode 不处理 hidden，CommandService 处理）', () => { ... });
});