Phase 1 Technisches Design-Dokument: Infrastruktur-Neubau

/**
 * Aufzählung der Ausführungsmodi.
 * - interactive: React/Ink UI-Modus (Terminal-Interaktion)
 * - non_interactive: Nicht-interaktiver CLI-Modus (Text/JSON-Ausgabe)
 * - acp: ACP/Zed-Integrationsmodus
 */
export type ExecutionMode = 'interactive' | 'non_interactive' | 'acp';

/**
 * Aufzählung der Befehlsquellen, für Hilfe-Gruppierung, Autovervollständigungs-Badge, ACP available commands.
 *
 * Unterschied zu CommandKind:
 * - CommandKind ist eine interne Lader-Klassifizierung (4 Arten), beeinflusst die Ladelogik
 * - CommandSource ist eine benutzerorientierte Quellenklassifizierung (9 Arten), beeinflusst Darstellung und mentales Modell
 *
 * Beide können sich überschneiden, haben aber unterschiedliche Aufgaben und werden nicht zusammengeführt.
 */
export type CommandSource =
  | 'builtin-command' // Integrierter Befehl (BuiltinCommandLoader)
  | 'bundled-skill'   // Mitgeliefertes Skill (BundledSkillLoader)
  | 'skill-dir-command' // Benutzer-/Projekt-Befehl unter .qwen/commands/ (FileCommandLoader, kein Plugin)
  | 'plugin-command'  // Von einem Plugin bereitgestellter Befehl (FileCommandLoader, extensionName nicht leer)
  | 'mcp-prompt';     // Von einem MCP-Server bereitgestellter Prompt (McpPromptLoader)
// Folgende Quellen sind reserviert, werden in Phase 1 nicht implementiert, aber das Schema ist vorab definiert:
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * Befehlsausführungstyp, beschreibt "wie" der Befehl ausgeführt wird.
 *
 * - prompt: Erzeugt submit_prompt, reicht den Inhalt an das Modell weiter. Geeignet für Skills, File-Commands, MCP-Prompts.
 *   Standardmäßig sind alle Modi unterstützt, standardmäßig ist modelInvocable true.
 *
 * - local: Führt Logik lokal aus, ohne Abhängigkeit von React/Ink UI. Kann message, stream_messages,
 *   submit_prompt, tool usw. zurückgeben. Geeignet für integrierte Befehle zum Abfragen, Konfigurieren, Status.
 *   Standardmäßig ist supportedModes ['interactive']; für nicht-interaktive Unterstützung muss supportedModes explizit deklariert werden.
 *   Dies entspricht der Semantik von Claude Codes supportsNonInteractive: true – nicht-interaktive Unterstützung erfordert explizite Deklaration, keine automatische Ableitung.
 *
 * - local-jsx: Abhängig von React/Ink UI (Dialog öffnen, JSX-Komponenten rendern usw.)
 *   Standardmäßig ist supportedModes nur ['interactive'].
 */
export type CommandType = 'prompt' | 'local' | 'local-jsx';

export interface SlashCommand {
  // ── Bestehende Felder (unverändert) ──────────────────────────────────────────────
  name: string;
  altNames?: string[];
  description: string;
  hidden?: boolean;
  completionPriority?: number;
  kind: CommandKind;
  extensionName?: string;
  action?: (...) => ...;
  completion?: (...) => ...;
  subCommands?: SlashCommand[];
 
  // ── Phase 1 Neu: Quelle und Ausführungstyp ──────────────────────────────────────
  /**
   * Befehlsquelle, für Hilfe-Gruppierung, Autovervollständigungs-Badge, ACP available commands.
   * Wird von jedem Loader gesetzt, nicht vom Befehl selbst.
   * Wenn CommandKind in Zukunft entfernt wird, wird source der einzige Quellenbezeichner sein.
   */
  source?: CommandSource;
 
  /**
   * Anzeigelabel der Quelle, benutzerorientiert.
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * Wird von jedem Loader gesetzt, kann vom Befehl selbst überschrieben werden.
   */
  sourceLabel?: string;
 
  /**
   * Befehlsausführungstyp.
   * - Von Loadern werden Standardwerte gesetzt (prompt/local-jsx)
   * - Integrierte Befehle werden von der jeweiligen Befehlsdatei selbst deklariert (local oder local-jsx)
   * Standardstrategie bei fehlender Deklaration siehe getEffectiveCommandType().
   */
  commandType?: CommandType;
 
  // ── Phase 1 Neu: Modusfähigkeit ──────────────────────────────────────────
  /**
   * In welchen Ausführungsmodi dieser Befehl verfügbar ist.
   * Bei fehlender Deklaration wird basierend auf commandType ein Standardwert abgeleitet (siehe getEffectiveSupportedModes()).
   * Explizite Deklaration hat Vorrang vor abgeleitetem Wert.
   */
  supportedModes?: ExecutionMode[];
 
  // ── Phase 1 Neu: Sichtbarkeit ──────────────────────────────────────────────
  /**
   * Kann der Benutzer diesen Befehl über den Slash-Command aufrufen?
   * Standard true (fast alle Befehle sind userInvocable).
   */
  userInvocable?: boolean;
 
  /**
   * Kann das Modell diesen Befehl per Tool-Call aufrufen?
   * Standard false. Befehle vom Typ prompt (Skills, File-Commands, MCP-Prompts) sollten true sein.
   * Integrierte Befehle erlauben keinen Modellaufruf (immer false).
   */
  modelInvocable?: boolean;
 
  // ── Phase 3 reserviert: Erlebnis-Metadaten (Phase 1 nur Definition, keine Verwendung) ──────────────────
  /**
   * Parameterhinweis, angezeigt im Autovervollständigungsmenü nach dem Befehlsnamen.
   * Beispiel: "<model-id>" / "show|list|set <id>" / "[--fast] [<model-id>]"
   */
  argumentHint?: string;
 
  /**
   * Erklärung für das Modell, wann dieser Befehl aufgerufen werden sollte.
   * Wird in die Beschreibung von modelInvocable-Befehlen eingefügt.
   */
  whenToUse?: string;
 
  /**
   * Nutzungsbeispiele, für Hilfe-Inhalte und Autovervollständigung.
   */
  examples?: string[];
}

// Setzt source/sourceLabel/commandType nicht – wird von jeder Befehlsdatei selbst deklariert
// Da integrierte Befehle vom Typ local oder local-jsx sind, müssen sie einzeln gekennzeichnet werden
 
// Injiziert source und sourceLabel:
for (const cmd of rawCommands) {
  enrichedCommands.push({
    ...cmd,
    source: 'builtin-command',
    sourceLabel: 'Built-in',
    userInvocable: cmd.userInvocable ?? true,
    modelInvocable: false, // Integrierte Befehle erlauben keinen Modellaufruf
  });
}

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

// In createSlashCommandFromDefinition:
return {
  name: baseCommandName,
  description,
  kind: CommandKind.FILE,
  extensionName,
  // source hängt von extensionName ab:
  source: extensionName ? 'plugin-command' : 'skill-dir-command',
  sourceLabel: extensionName ? `Plugin: ${extensionName}` : 'Custom',
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: !extensionName, // Plugin-Befehle vorerst kein Modellaufruf; Benutzer-/Projektbefehle erlauben
  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,
  // ... restliche bestehende Felder
};

/**
 * Ermittelt die tatsächliche Liste der unterstützten Modi für einen Befehl.
 *
 * Ableitungspriorität (höchste zu niedrigster):
 * 1. Explizit deklariertes supportedModes des Befehls (höchste Priorität)
 * 2. Ableitung basierend auf commandType
 * 3. Fallback basierend auf CommandKind (Rückwärtskompatibilität)
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // Priorität 1: Explizite Deklaration
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // Priorität 2: Ableitung basierend auf commandType
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // prompt-Typ hat keine UI-Abhängigkeit, von Haus aus in allen Modi verfügbar
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // local-Typ konservativer Standard: nur interactive.
        // Befehle, die nicht-interaktive Unterstützung benötigen, müssen supportedModes explizit deklarieren
        // (entspricht Claude Codes supportsNonInteractive: true).
        // In Phase 2 werden sie einzeln validiert und freigeschaltet, um zu vermeiden, dass unangepasste
        // Befehle versehentlich headless-Aufrufern ausgesetzt werden.
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // Priorität 3: Fallback (basierend auf CommandKind, für Rückwärtskompatibilität mit altem Code)
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // Integrierte Befehle ohne commandType-Deklaration: konservativer Standard (nur interactive)
      // Dieser Zweig sollte nach Abschluss von Phase 1 nicht mehr erreicht werden
      // (alle integrierten Befehle haben dann commandType)
      return ['interactive'];
    case CommandKind.FILE:
    case CommandKind.SKILL:
    case CommandKind.MCP_PROMPT:
      // Diese drei Befehlstypen haben von Natur aus keine UI-Abhängigkeit;
      // historisch auch in allen Modi verfügbar
      return ['interactive', 'non_interactive', 'acp'];
    default:
      return ['interactive'];
  }
}

/**
 * Filtert Befehle basierend auf supportedModes für den aktuellen Modus.
 * Ersetzt die bisherige filterCommandsForNonInteractive-Funktion.
 */
export function filterCommandsForMode(
  commands: readonly SlashCommand[],
  mode: ExecutionMode,
): SlashCommand[] {
  return commands.filter((cmd) =>
    getEffectiveSupportedModes(cmd).includes(mode),
  );
}

export class CommandService {
  // ── Bestehende Methode (unverändert) ────────────────────────────────────────────────
  getCommands(): readonly SlashCommand[] {
    return this.commands;
  }
 
  // ── Phase 1 Neue Methoden ──────────────────────────────────────────────────
 
  /**
   * Gibt die Liste der im angegebenen Ausführungsmodus verfügbaren Befehle zurück.
   * Ersetzt die Kombination aus bisheriger Whitelist + filterCommandsForNonInteractive.
   *
   * @param mode Ziel-Ausführungsmodus
   * @returns Liste der für diesen Modus geeigneten Befehle (ohne hidden-Befehle)
   */
  getCommandsForMode(mode: ExecutionMode): readonly SlashCommand[] {
    return this.commands.filter((cmd) => {
      if (cmd.hidden) return false;
      return getEffectiveSupportedModes(cmd).includes(mode);
    });
  }
 
  /**
   * Gibt alle Befehle zurück, bei denen modelInvocable true ist.
   * In Phase 2 wird SkillTool diese Methode konsumieren; Phase 1 stellt nur die Schnittstelle bereit.
   *
   * @returns Liste der vom Modell aufrufbaren Befehle
   */
  getModelInvocableCommands(): readonly SlashCommand[] {
    return this.commands.filter(
      (cmd) => !cmd.hidden && cmd.modelInvocable === true,
    );
  }
}

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

// ✅ Neu (oder Import aus commandUtils)
import { filterCommandsForMode } from '../services/commandUtils.js';

// ❌ Alte Signatur
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<NonInteractiveSlashCommandResult>
 
// ✅ Neue Signatur (Entfernung von allowedBuiltinCommandNames)
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
): Promise<NonInteractiveSlashCommandResult>

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

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

// ❌ Alter Aufruf
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
  // Nicht übergeben – Standard-Whitelist wird verwendet
);
 
// ✅ Neuer Aufruf (keine Änderung – nicht mehr vorhandener Standardparameter entfällt)
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
);
 
// ─────────────────────────────────────────
 
// ❌ Alter Aufruf
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
);
 
// ✅ Neuer Aufruf (expliziter mode)
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 处理）', () => { ... });
});