Phase 1 Technisches Design-Dokument: Infrastruktur-Neuaufbau

/**
 * Ausführungsmodus-Enumeration.
 * - interactive: React/Ink UI-Modus (Terminal-Interaktion)
 * - non_interactive: Non-Interactive CLI-Modus (Text/JSON-Ausgabe)
 * - acp: ACP/Zed-Integrationsmodus
 */
export type ExecutionMode = 'interactive' | 'non_interactive' | 'acp';

/**
 * Befehlsquellen-Enumeration, verwendet für Help-Gruppierung, Completion-Badges und ACP available commands.
 *
 * Unterschied zu CommandKind:
 * - CommandKind ist die interne Loader-Klassifizierung (4 Arten), die die Ladelogik beeinflusst
 * - CommandSource ist die benutzerorientierte Quellenklassifizierung (9 Arten), die die Darstellung und das mentale Modell beeinflusst
 *
 * Beide können sich überschneiden, haben aber unterschiedliche Verantwortlichkeiten und werden nicht zusammengeführt.
 */
export type CommandSource =
  | 'builtin-command' // Eingebaute Befehle (BuiltinCommandLoader)
  | 'bundled-skill' // Mit dem Paket verteilte Skills (BundledSkillLoader)
  | 'skill-dir-command' // Datei-Befehle unter .qwen/commands/ des Users/Projekts (FileCommandLoader, kein Plugin)
  | 'plugin-command' // Von Plugins bereitgestellte Befehle (FileCommandLoader, extensionName nicht leer)
  | 'mcp-prompt'; // Vom MCP-Server bereitgestellter Prompt (McpPromptLoader)
// Folgende Quellen sind reserviert, in Phase 1 nicht implementiert, aber Schema vordefiniert:
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * Befehlsausführungstyp, beschreibt "wie" der Befehl ausgeführt wird.
 *
 * - prompt: Erzeugt submit_prompt, übergibt Inhalt an das Modell. Geeignet für Skills, File Commands, MCP Prompts.
 *   Standard-supportedModes: alle Modi, Standard-modelInvocable: true.
 *
 * - local: Lokale Ausführungslogik, keine Abhängigkeit von React/Ink UI. Kann message, stream_messages,
 *   submit_prompt, tool etc. zurückgeben. Geeignet für Query-, Konfigurations- und Status-Built-in-Befehle.
 *   Standard-supportedModes: ['interactive'], muss explizit deklariert werden, um für andere Modi freigegeben zu werden.
 *   Dies entspricht der Semantik von supportsNonInteractive: true in Claude Code – Non-Interactive-Unterstützung muss explizit deklariert werden, nicht automatisch inferiert.
 *
 * - local-jsx: Befehle, die von React/Ink UI abhängen (Dialog öffnen, JSX-Komponenten rendern etc.).
 *   Standard-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, verwendet für Help-Gruppierung, Completion-Badges und ACP available commands.
   * Wird vom Loader befüllt, nicht vom Befehl selbst deklariert.
   * Wenn CommandKind zukünftig deprecated wird, wird source die einzige Quellenkennung.
   */
  source?: CommandSource;
 
  /**
   * Benutzerorientiertes Quellen-Label für die Anzeige.
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * Wird vom Loader befüllt, kann vom Befehl selbst überschrieben werden.
   */
  sourceLabel?: string;
 
  /**
   * Befehlsausführungstyp.
   * - Loader befüllt Standardwerte (prompt/local-jsx)
   * - Built-in-Befehle deklarieren ihn in der jeweiligen Befehlsdatei (local oder local-jsx)
   * Standardstrategie bei fehlender Deklaration siehe getEffectiveCommandType().
   */
  commandType?: CommandType;
 
  // ── Phase 1 neu: Modus-Fähigkeiten ──────────────────────────────────────────
  /**
   * In welchen Ausführungsmodi dieser Befehl verfügbar ist.
   * Bei fehlender Deklaration wird der Standardwert basierend auf commandType inferiert (siehe getEffectiveSupportedModes()).
   * Explizite Deklaration hat Vorrang vor dem inferierten Wert.
   */
  supportedModes?: ExecutionMode[];
 
  // ── Phase 1 neu: Sichtbarkeit ──────────────────────────────────────────────
  /**
   * Ob der Benutzer diesen Befehl über einen Slash-Command aufrufen kann.
   * Standard: true (fast alle Befehle sind userInvocable).
   */
  userInvocable?: boolean;
 
  /**
   * Ob das Modell diesen Befehl über einen Tool-Call aufrufen kann.
   * Standard: false. Befehle vom Typ prompt (Skills, File Commands, MCP Prompts) sollten auf true gesetzt werden.
   * Built-in-Befehle dürfen nicht vom Modell aufgerufen werden (immer false).
   */
  modelInvocable?: boolean;
 
  // ── Phase 3 reserviert: Experience-Metadaten (Phase 1 nur definiert, nicht verwendet) ──────────────────
  /**
   * Parameter-Hinweis, angezeigt nach dem Befehlsnamen im Completion-Menü.
   * Beispiel: "<model-id>" / "show|list|set <id>" / "[--fast] [<model-id>]"
   */
  argumentHint?: string;
 
  /**
   * Beschreibung, wann das Modell diesen Befehl aufrufen soll.
   * Wird in die description von modelInvocable-Befehlen injiziert.
   */
  whenToUse?: string;
 
  /**
   * Verwendungsbeispiele für die Help-Dokumentation und Completion-Anzeige.
   */
  examples?: string[];
}

// source/sourceLabel/commandType nicht befüllen — wird von den Befehlsdateien selbst deklariert
// Da der commandType von Built-in-Befehlen local oder local-jsx ist, muss er einzeln annotiert werden
 
// source und sourceLabel injizieren:
for (const cmd of rawCommands) {
  enrichedCommands.push({
    ...cmd,
    source: 'builtin-command',
    sourceLabel: 'Built-in',
    userInvocable: cmd.userInvocable ?? true,
    modelInvocable: false, // Built-in-Befehle dürfen nicht vom Modell aufgerufen werden
  });
}

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 wird basierend auf extensionName bestimmt:
  source: extensionName ? 'plugin-command' : 'skill-dir-command',
  sourceLabel: extensionName ? `Plugin: ${extensionName}` : 'Custom',
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: !extensionName, // Plugin-Befehle vorerst nicht für Modell-Aufrufe, User/Projekt-Befehle erlaubt
  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ächlich unterstützten Modi eines Befehls.
 *
 * Inferenzpriorität (von hoch nach niedrig):
 * 1. Explizit deklarierter supportedModes (höchste Priorität)
 * 2. Inferenz basierend auf commandType
 * 3. Fallback basierend auf CommandKind (Abwärtskompatibilität)
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // Priorität 1: Explizite Deklaration
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // Priorität 2: Inferenz basierend auf commandType
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // Prompt-Typ hat keine UI-Abhängigkeiten, standardmäßig in allen Modi verfügbar
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // Local-Typ konservativer Standard: nur interactive.
        // Befehle, die Non-Interactive-Unterstützung benötigen, müssen supportedModes explizit deklarieren (entspricht supportsNonInteractive: true in Claude Code).
        // In Phase 2 einzeln validieren und freischalten, um zu verhindern, dass nicht angepasste Befehle Headless-Aufrufern ungewollt ausgesetzt werden.
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // Priorität 3: Fallback (basierend auf CommandKind, Abwärtskompatibilität für alten Code)
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // Built-in-Befehle ohne commandType-Deklaration: konservativer Standard (nur interactive)
      // Dieser Branch sollte nach Abschluss von Phase 1 nicht mehr erreicht werden (alle Built-in-Befehle haben commandType)
      return ['interactive'];
    case CommandKind.FILE:
    case CommandKind.SKILL:
    case CommandKind.MCP_PROMPT:
      // Diese drei Befehlstypen haben action-Implementierungen ohne UI-Abhängigkeiten, historisch 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 ursprüngliche filterCommandsForNonInteractive-Funktion.
 */
export function filterCommandsForMode(
  commands: readonly SlashCommand[],
  mode: ExecutionMode,
): SlashCommand[] {
  return commands.filter((cmd) =>
    getEffectiveSupportedModes(cmd).includes(mode),
  );
}

export class CommandService {
  // ── Bestehende Methoden (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 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.
   * SkillTool wird diese Methode in Phase 2 konsumieren; Phase 1 stellt nur das Interface 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 aus commandUtils importieren)
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 (allowedBuiltinCommandNames entfernt)
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, verwendet Standard-Whitelist
);
 
// ✅ Neuer Aufruf (keine Änderung, entfernter Default-Parameter existiert nicht mehr)
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
);
 
// ─────────────────────────────────────────
 
// ❌ Alter Aufruf
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
);
 
// ✅ Neuer Aufruf (Modus explizit angegeben)
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
  'acp',
);

// ① Interactive-Version: local-jsx, nur interactive
export const modelCommandInteractive: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local-jsx',
  supportedModes: ['interactive'], // Explizit eingeschränkt
  // action: Öffnet Dialog zur Model-Auswahl
};
 
// ② Non-Interactive/ACP-Version: local, explizit für Headless-Aufrufe freigegeben
export const modelCommandHeadless: SlashCommand = {
  name: 'model',
  kind: CommandKind.BUILT_IN,
  commandType: 'local',
  supportedModes: ['non_interactive', 'acp'], // Explizit eingeschränkt
  // action: Liest/setzt Model, gibt message zurück (reiner Text)
};

describe('getEffectiveSupportedModes', () => {
  it('Explizite supportedModes haben Vorrang vor commandType-Inferenz', () => {
    const cmd: SlashCommand = {
      name: 'test', description: '', kind: CommandKind.BUILT_IN,
      commandType: 'local',
      supportedModes: ['interactive'], // Explizit eingeschränkt
    };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: local inferiert zu 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 inferiert zu interactive only', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local-jsx' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: prompt inferiert zu all modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.SKILL, commandType: 'prompt' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('Fehlende commandType-Deklaration und CommandKind.BUILT_IN, Fallback zu interactive', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('Fehlende commandType-Deklaration und CommandKind.FILE, Fallback zu all modes', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.FILE };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('Fehlende commandType-Deklaration und CommandKind.MCP_PROMPT, Fallback zu all modes (behebt ursprüngliche Einschränkung)', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.MCP_PROMPT };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
});
 
describe('filterCommandsForMode', () => {
  it('Filtert Befehle im non_interactive-Modus korrekt', () => { ... });
  it('Filtert Befehle im acp-Modus korrekt', () => { ... });
  it('Filtert hidden-Befehle nicht (filterCommandsForMode behandelt hidden nicht, CommandService übernimmt dies)', () => { ... });
});