Phase 1 技術設計ドキュメント：インフラストラクチャ再構築

/**
 * 実行モードの列挙型。
 * - interactive：React/Ink UI モード（ターミナルインタラクション）
 * - non_interactive：非インタラクティブ CLI モード（テキスト/JSON 出力）
 * - acp：ACP/Zed 統合モード
 */
export type ExecutionMode = 'interactive' | 'non_interactive' | 'acp';

/**
 * コマンドのソースを定義する列挙型。Help のグループ化、補完バッジ、ACP available commands の表示に使用。
 *
 * CommandKind との違い：
 * - CommandKind は内部ローダー分類（4種類）であり、読み込みロジックに影響する
 * - CommandSource はユーザー向けのソース分類（9種類）であり、表示とメンタルモデルに影響する
 *
 * 両者は重複する可能性があるが、責務が異なるため統合しない。
 */
export type CommandSource =
  | 'builtin-command' // 組み込みコマンド（BuiltinCommandLoader）
  | 'bundled-skill' // パッケージに同梱される skill（BundledSkillLoader）
  | 'skill-dir-command' // ユーザー/プロジェクト .qwen/commands/ 配下のファイルコマンド（FileCommandLoader、プラグイン以外）
  | 'plugin-command' // プラグインが提供するコマンド（FileCommandLoader、extensionName が空でない）
  | 'mcp-prompt'; // MCP server が提供する prompt（McpPromptLoader）
// 以下のソースは予約済み。Phase 1 では対応 Loader を実装しないが、スキーマは事前に定義：
// | 'workflow-command'
// | 'plugin-skill'
// | 'dynamic-skill'
// | 'builtin-plugin-skill'
// | 'mcp-skill'

/**
 * コマンドの実行タイプ。コマンドが「どのように実行されるか」を記述する。
 *
 * - prompt：submit_prompt を生成し、コンテンツをモデルに送信する。skill、file command、MCP prompt に適用。
 *   デフォルトの supportedModes は全モード、デフォルトの modelInvocable は true。
 *
 * - local：ローカルでロジックを実行し、React/Ink UI に依存しない。message、stream_messages、
 *   submit_prompt、tool などのタイプを返す。クエリ系、設定系、ステータス系の built-in コマンドに適用。
 *   デフォルトの supportedModes は ['interactive']。他のモードに開放するには明示的に supportedModes を宣言する必要がある。
 *   これは Claude Code の supportsNonInteractive: true のセマンティクスと一致する——非インタラクティブサポートは自動推論ではなく明示的に宣言する必要がある。
 *
 * - local-jsx：React/Ink UI に依存するコマンド（dialog の開閉、JSX コンポーネントのレンダリングなど）。
 *   デフォルトの supportedModes は ['interactive'] のみ。
 */
export type CommandType = 'prompt' | 'local' | 'local-jsx';

export interface SlashCommand {
  // ── 既存フィールド（変更なし） ──────────────────────────────────────────────
  name: string;
  altNames?: string[];
  description: string;
  hidden?: boolean;
  completionPriority?: number;
  kind: CommandKind;
  extensionName?: string;
  action?: (...) => ...;
  completion?: (...) => ...;
  subCommands?: SlashCommand[];
 
  // ── Phase 1 新規追加：ソースと実行タイプ ──────────────────────────────────────
  /**
   * コマンドのソース。Help のグループ化、補完バッジ、ACP available commands の表示に使用。
   * 各 Loader によって設定され、コマンド自身では宣言しない。
   * 将来的に CommandKind を廃止する場合、source が唯一のソース識別子となる。
   */
  source?: CommandSource;
 
  /**
   * ユーザー向けの表示用ソースラベル。
   * - builtin-command → "Built-in"
   * - bundled-skill → "Skill"
   * - skill-dir-command → "Custom"
   * - plugin-command → "Plugin: <extensionName>"
   * - mcp-prompt → "MCP: <serverName>"
   * 各 Loader によって設定され、コマンド自身で上書き可能。
   */
  sourceLabel?: string;
 
  /**
   * コマンドの実行タイプ。
   * - 各 Loader がデフォルト値（prompt/local-jsx）を設定
   * - 組み込みコマンドはコマンドファイル自身で宣言（local または local-jsx）
   * 未宣言時のデフォルト戦略は getEffectiveCommandType() を参照。
   */
  commandType?: CommandType;
 
  // ── Phase 1 新規追加：モード機能 ──────────────────────────────────────────
  /**
   * このコマンドが利用可能な実行モード。
   * 未宣言時は commandType に基づいてデフォルト値が推論される（getEffectiveSupportedModes() を参照）。
   * 明示的な宣言は推論値より優先される。
   */
  supportedModes?: ExecutionMode[];
 
  // ── Phase 1 新規追加：可視性 ──────────────────────────────────────────────
  /**
   * ユーザーが slash command 経由でこのコマンドを呼び出せるかどうか。
   * デフォルトは true（ほぼすべてのコマンドが userInvocable）。
   */
  userInvocable?: boolean;
 
  /**
   * モデルが tool call 経由でこのコマンドを呼び出せるかどうか。
   * デフォルトは false。prompt タイプのコマンド（skill、file command、MCP prompt）は true に設定する必要がある。
   * 組み込みコマンドはモデル呼び出しを許可しない（常に false）。
   */
  modelInvocable?: boolean;
 
  // ── Phase 3 予約：UX メタデータ（Phase 1 では定義のみ、使用しない）──────────────────
  /**
   * 引数ヒント。補完メニューのコマンド名後に表示される。
   * 例："<model-id>" / "show|list|set <id>" / "[--fast] [<model-id>]"
   */
  argumentHint?: string;
 
  /**
   * モデルがいつこのコマンドを呼び出すべきかを理解するための説明。
   * modelInvocable コマンドの description に注入される。
   */
  whenToUse?: string;
 
  /**
   * 使用例。Help ディレクトリと補完表示に使用。
   */
  examples?: string[];
}

// source/sourceLabel/commandType は設定しない — 各コマンドファイルで自己宣言するため
// 組み込みコマンドの commandType は local または local-jsx であり、個別に指定する必要があるため
 
// source と sourceLabel を注入：
for (const cmd of rawCommands) {
  enrichedCommands.push({
    ...cmd,
    source: 'builtin-command',
    sourceLabel: 'Built-in',
    userInvocable: cmd.userInvocable ?? true,
    modelInvocable: false, // 組み込みコマンドはモデル呼び出しを許可しない
  });
}

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

// createSlashCommandFromDefinition 内：
return {
  name: baseCommandName,
  description,
  kind: CommandKind.FILE,
  extensionName,
  // source は extensionName に応じて決定：
  source: extensionName ? 'plugin-command' : 'skill-dir-command',
  sourceLabel: extensionName ? `Plugin: ${extensionName}` : 'Custom',
  commandType: 'prompt',
  userInvocable: true,
  modelInvocable: !extensionName, // プラグインコマンドは当面モデル呼び出しを許可しない。ユーザー/プロジェクトコマンドは許可
  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,
  // ... その他の既存フィールド
};

/**
 * コマンドが実際にサポートするモードのリストを取得する。
 *
 * 推論の優先度（高 → 低）：
 * 1. コマンドが明示的に宣言した supportedModes（最優先）
 * 2. commandType に基づく推論
 * 3. CommandKind に基づくフォールバック（旧コードとの後方互換性維持）
 */
export function getEffectiveSupportedModes(cmd: SlashCommand): ExecutionMode[] {
  // 優先度 1：明示的な宣言
  if (cmd.supportedModes !== undefined) {
    return cmd.supportedModes;
  }
 
  // 優先度 2：commandType に基づく推論
  if (cmd.commandType !== undefined) {
    switch (cmd.commandType) {
      case 'prompt':
        // prompt タイプは UI 依存がないため、デフォルトで全モードで利用可能
        return ['interactive', 'non_interactive', 'acp'];
      case 'local':
        // local タイプの保守的なデフォルト：interactive のみ。
        // 非インタラクティブサポートが必要なコマンドは明示的に supportedModes を宣言する必要がある（Claude Code の supportsNonInteractive: true に相当）。
        // Phase 2 で個別に検証・解放し、未対応のコマンドが headless 呼び出し元に誤って公開されるのを防ぐ。
        return ['interactive'];
      case 'local-jsx':
        return ['interactive'];
    }
  }
 
  // 優先度 3：フォールバック（CommandKind に基づく。旧コードとの後方互換性維持）
  switch (cmd.kind) {
    case CommandKind.BUILT_IN:
      // 組み込みコマンドで commandType が未宣言の場合の保守的なデフォルト（interactive のみ）
      // この分岐は Phase 1 完了後には到達しないはず（すべての組み込みコマンドに commandType が設定されるため）
      return ['interactive'];
    case CommandKind.FILE:
    case CommandKind.SKILL:
    case CommandKind.MCP_PROMPT:
      // これら3種類のコマンドの action は本質的に UI 依存がなく、歴史的にも全モードで利用可能
      return ['interactive', 'non_interactive', 'acp'];
    default:
      return ['interactive'];
  }
}

/**
 * supportedModes に基づき、現在のモードに適したコマンドをフィルタリングする。
 * 既存の filterCommandsForNonInteractive 関数を置き換える。
 */
export function filterCommandsForMode(
  commands: readonly SlashCommand[],
  mode: ExecutionMode,
): SlashCommand[] {
  return commands.filter((cmd) =>
    getEffectiveSupportedModes(cmd).includes(mode),
  );
}

export class CommandService {
  // ── 既存メソッド（変更なし）────────────────────────────────────────────────
  getCommands(): readonly SlashCommand[] {
    return this.commands;
  }
 
  // ── Phase 1 新規追加メソッド ──────────────────────────────────────────────────
 
  /**
   * 指定された実行モードで利用可能なコマンドのリストを返す。
   * 既存のホワイトリスト + filterCommandsForNonInteractive の組み合わせを置き換える。
   *
   * @param mode 対象の実行モード
   * @returns 当該モードに適したコマンドリスト（hidden コマンドを除く）
   */
  getCommandsForMode(mode: ExecutionMode): readonly SlashCommand[] {
    return this.commands.filter((cmd) => {
      if (cmd.hidden) return false;
      return getEffectiveSupportedModes(cmd).includes(mode);
    });
  }
 
  /**
   * modelInvocable が true のすべてのコマンドを返す。
   * Phase 2 で SkillTool がこのメソッドを消費する。Phase 1 ではインターフェースのみ提供。
   *
   * @returns モデルが呼び出せるコマンドリスト
   */
  getModelInvocableCommands(): readonly SlashCommand[] {
    return this.commands.filter(
      (cmd) => !cmd.hidden && cmd.modelInvocable === true,
    );
  }
}

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

// ✅ 追加（または commandUtils からインポート）
import { filterCommandsForMode } from '../services/commandUtils.js';

// ❌ 旧シグネチャ
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<NonInteractiveSlashCommandResult>
 
// ✅ 新シグネチャ（allowedBuiltinCommandNames を削除）
export const handleSlashCommand = async (
  rawQuery: string,
  abortController: AbortController,
  config: Config,
  settings: LoadedSettings,
): Promise<NonInteractiveSlashCommandResult>

// 旧：
const filteredCommands = filterCommandsForNonInteractive(
  allCommands,
  allowedBuiltinSet,
);
 
// 新：
const executionMode = isAcpMode ? 'acp' : 'non_interactive';
const filteredCommands = filterCommandsForMode(allCommands, executionMode);

// ❌ 旧シグネチャ
export const getAvailableCommands = async (
  config: Config,
  abortSignal: AbortSignal,
  allowedBuiltinCommandNames: string[] = [...ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE],
): Promise<SlashCommand[]>
 
// ✅ 新シグネチャ
export const getAvailableCommands = async (
  config: Config,
  abortSignal: AbortSignal,
  mode: ExecutionMode = 'acp',
): Promise<SlashCommand[]>

// ❌ 旧呼び出し
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
  // 渡さない（デフォルトのホワイトリストを使用）
);
 
// ✅ 新呼び出し（変更なし。存在しなくなったデフォルトパラメータを削除）
const slashCommandResult = await handleSlashCommand(
  inputText,
  abortController,
  this.config,
  this.settings,
);
 
// ─────────────────────────────────────────
 
// ❌ 旧呼び出し
const slashCommands = await getAvailableCommands(
  this.config,
  abortController.signal,
);
 
// ✅ 新呼び出し（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 が全モードに推論される', () => {
    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 のみに推論される', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.BUILT_IN, commandType: 'local-jsx' };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive']);
  });
 
  it('commandType: prompt が全モードに推論される', () => {
    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 の場合、フォールバックで全モードとなる', () => {
    const cmd: SlashCommand = { name: 'test', description: '', kind: CommandKind.FILE };
    expect(getEffectiveSupportedModes(cmd)).toEqual(['interactive', 'non_interactive', 'acp']);
  });
 
  it('commandType が未宣言かつ CommandKind.MCP_PROMPT の場合、フォールバックで全モードとなる（既存の制限を修正）', () => {
    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 が処理する）', () => { ... });
});