@dusky-bluehour/agent-service 0.6.2

package/scripts/init.mjs

@@ -0,0 +1,993 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { stdin as input, stdout as output } from 'node:process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+const catalogPath = path.join(rootDir, 'catalog', 'tool-catalog.ko.json');
+const packageJsonPath = path.join(rootDir, 'package.json');
+const CLI_NAME = 'tri-agent-manager';
+const CLI_COMPAT_NAME = 'tri-agent-os';
+const STATE_DIR_NAME = '.tri-agent-manager';
+const LEGACY_STATE_DIR_NAME = '.tri-agent-os';
+
+const HELP_TEXT = [
+  `${CLI_NAME} 사용법`,
+  '',
+  '명령:',
+  `  ${CLI_NAME} list`,
+  `  ${CLI_NAME} setup   (install + interactive 별칭)`,
+  `  ${CLI_NAME} wizard  (install + interactive 별칭)`,
+  `  ${CLI_NAME} install [--preset <id>] [--tool <ids>] [--components <ids>] [--target <path>] [--force] [--dry-run] [--yes]`,
+  `  ${CLI_NAME} update  [--preset <id>] [--tool <ids>] [--components <ids>] [--target <path>] [--dry-run] [--yes]`,
+  `  ${CLI_NAME} init    (install의 별칭)`,
+  '',
+  '옵션:',
+  '  --preset      프리셋 선택 (예: balanced-core, full-suite)',
+  '  --tool        도구 선택 (예: codex,claude-code) / all',
+  '  --components  구성요소 선택 (예: skills,workflows,commands) / all',
+  '  --target      설치 경로 (기본: .)',
+  '  --force       install 시 기존 파일 덮어쓰기',
+  '  --dry-run     복사하지 않고 작업 계획만 출력',
+  '  --yes         확인 프롬프트 생략',
+  '  --interactive 대화형 선택 모드 강제',
+  '  --non-interactive 비대화형 모드 강제',
+  '  (중복 선택 입력은 자동으로 1회로 정리됨)',
+  '',
+  '호환 별칭:',
+  `  ${CLI_COMPAT_NAME} ... (동일 동작)`,
+  '',
+  'pnpm 예시:',
+  '  pnpm dlx tri-agent-manager --interactive',
+  '  pnpm dlx tri-agent-manager update --interactive',
+  '  pnpm dlx tri-agent-manager setup',
+  `  pnpm exec ${CLI_NAME} list`
+].join('\n');
+
+function parseArgs(argv) {
+  const args = [...argv];
+  let command = 'install';
+
+  if (args.length > 0 && !args[0].startsWith('--')) {
+    command = args.shift();
+  }
+
+  const getFlag = (name) => {
+    const idx = args.indexOf(name);
+    if (idx === -1) return undefined;
+    const value = args[idx + 1];
+    if (!value || value.startsWith('--')) return undefined;
+    return value;
+  };
+
+  const hasFlag = (name) => args.includes(name);
+
+  return {
+    command,
+    presetFlag: getFlag('--preset'),
+    toolFlag: getFlag('--tool'),
+    componentFlag: getFlag('--components'),
+    targetFlag: getFlag('--target') ?? '.',
+    force: hasFlag('--force'),
+    dryRun: hasFlag('--dry-run'),
+    yes: hasFlag('--yes'),
+    interactive: hasFlag('--interactive'),
+    nonInteractive: hasFlag('--non-interactive')
+  };
+}
+
+async function readJson(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseCsv(value) {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function parseChoiceInput(rawInput, entries, defaultIds = []) {
+  const normalized = (rawInput ?? '').trim();
+  if (!normalized) {
+    return unique(defaultIds.length > 0 ? defaultIds : entries.map((e) => e.id));
+  }
+
+  if (normalized === 'all' || normalized === '*') {
+    return entries.map((e) => e.id);
+  }
+
+  const indexMap = new Map(entries.map((entry, index) => [String(index + 1), entry.id]));
+  const idSet = new Set(entries.map((entry) => entry.id));
+  const tokens = normalized
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+
+  const selected = [];
+  for (const token of tokens) {
+    if (indexMap.has(token)) {
+      selected.push(indexMap.get(token));
+      continue;
+    }
+    if (idSet.has(token)) {
+      selected.push(token);
+      continue;
+    }
+    throw new Error(`알 수 없는 선택값: ${token}`);
+  }
+
+  return unique(selected);
+}
+
+function findTool(catalog, toolId) {
+  return catalog.tools.find((t) => t.id === toolId);
+}
+
+function findPreset(catalog, presetId) {
+  if (!presetId) return null;
+  const presets = Array.isArray(catalog.presets) ? catalog.presets : [];
+  const preset = presets.find((p) => p.id === presetId);
+  if (!preset) {
+    throw new Error(`지원하지 않는 preset: ${presetId}`);
+  }
+  return preset;
+}
+
+function resolveToolsFromPreset(preset, catalog) {
+  if (!preset) return [];
+  const toolIdSet = new Set(catalog.tools.map((t) => t.id));
+  const selected = unique(Array.isArray(preset.tools) ? preset.tools : []);
+  for (const toolId of selected) {
+    if (!toolIdSet.has(toolId)) {
+      throw new Error(`preset(${preset.id})에 존재하지 않는 tool이 포함됨: ${toolId}`);
+    }
+  }
+  return selected;
+}
+
+function resolveComponentsFromPreset(tool, preset) {
+  if (!preset) return [];
+  const requested = preset.components?.[tool.id];
+  if (!requested) return [];
+
+  const availableIds = tool.components.map((c) => c.id);
+  const availableSet = new Set(availableIds);
+  const uniqueRequested = unique(requested);
+  for (const componentId of uniqueRequested) {
+    if (!availableSet.has(componentId)) {
+      throw new Error(
+        `preset(${preset.id})에 존재하지 않는 구성요소가 포함됨: ${tool.id}/${componentId}`
+      );
+    }
+  }
+  return uniqueRequested;
+}
+
+function resolvePresetFromInput(rawInput, catalog, defaultPresetId = '') {
+  const normalized = (rawInput ?? '').trim() || defaultPresetId;
+  if (!normalized || normalized === '0' || normalized.toLowerCase() === 'manual') {
+    return null;
+  }
+
+  const presets = Array.isArray(catalog.presets) ? catalog.presets : [];
+  const indexMap = new Map(presets.map((preset, index) => [String(index + 1), preset.id]));
+  const presetId = indexMap.get(normalized) ?? normalized;
+  return findPreset(catalog, presetId);
+}
+
+function resolveToolsFromFlag(toolFlag, catalog) {
+  const toolEntries = catalog.tools;
+  if (!toolFlag || toolFlag === 'all') {
+    return toolEntries.map((t) => t.id);
+  }
+
+  const requested = parseCsv(toolFlag);
+  const toolIdSet = new Set(toolEntries.map((t) => t.id));
+  for (const id of requested) {
+    if (!toolIdSet.has(id)) {
+      throw new Error(`지원하지 않는 tool: ${id}`);
+    }
+  }
+  return unique(requested);
+}
+
+function resolveComponentsFromFlag(componentFlag, tool, mode) {
+  const availableIds = tool.components.map((c) => c.id);
+  if (!componentFlag || componentFlag === 'all') {
+    return availableIds;
+  }
+
+  const requested = parseCsv(componentFlag);
+  const availableSet = new Set(availableIds);
+  const invalid = requested.filter((id) => !availableSet.has(id));
+  if (invalid.length > 0) {
+    throw new Error(`[${tool.id}] 지원하지 않는 구성요소: ${invalid.join(', ')}`);
+  }
+
+  if (mode === 'update' && requested.length === 0) {
+    return availableIds;
+  }
+
+  return unique(requested);
+}
+
+function clearTuiScreen() {
+  output.write('\x1Bc');
+}
+
+function formatTuiLine(prefix, label, selected = false) {
+  const marker = selected ? '[x]' : '[ ]';
+  return `${prefix} ${marker} ${label}`;
+}
+
+function setRawMode(enabled) {
+  if (input.isTTY) {
+    input.setRawMode(enabled);
+  }
+}
+
+function renderTuiHeader(title, helpLine) {
+  clearTuiScreen();
+  output.write(`${title}\n`);
+  output.write(`${'='.repeat(title.length)}\n`);
+  output.write(`${helpLine}\n\n`);
+}
+
+function readKeypressOnce() {
+  return new Promise((resolve) => {
+    const handler = (str, key) => {
+      input.off('keypress', handler);
+      resolve({ str, key: key ?? {} });
+    };
+    input.on('keypress', handler);
+  });
+}
+
+async function askLine(question, defaultValue = '') {
+  setRawMode(false);
+  const rl = createInterface({ input, output });
+  try {
+    const suffix = defaultValue ? ` (기본: ${defaultValue})` : '';
+    const answer = await rl.question(`${question}${suffix}\n> `);
+    return answer.trim() || defaultValue;
+  } finally {
+    rl.close();
+    setRawMode(true);
+  }
+}
+
+async function runSingleSelectMenu({ title, help, options, defaultIndex = 0 }) {
+  let cursor = Math.min(Math.max(defaultIndex, 0), Math.max(options.length - 1, 0));
+
+  while (true) {
+    renderTuiHeader(title, help);
+    options.forEach((option, index) => {
+      const pointer = index === cursor ? '>' : ' ';
+      output.write(`${pointer} ${option.label}\n`);
+      if (option.description) {
+        output.write(`    ${option.description}\n`);
+      }
+    });
+
+    const { str, key } = await readKeypressOnce();
+    if (key.ctrl && key.name === 'c') {
+      throw new Error('사용자 취소');
+    }
+    if (str === 'q' || key.name === 'escape') {
+      throw new Error('사용자 취소');
+    }
+
+    if (key.name === 'up' || key.name === 'left') {
+      cursor = (cursor - 1 + options.length) % options.length;
+      continue;
+    }
+    if (key.name === 'down' || key.name === 'right') {
+      cursor = (cursor + 1) % options.length;
+      continue;
+    }
+    if (key.name === 'return' || key.name === 'enter') {
+      return options[cursor];
+    }
+  }
+}
+
+async function runMultiSelectMenu({
+  title,
+  help,
+  choices,
+  preselectedIds = [],
+  minSelected = 1
+}) {
+  const selected = new Set(preselectedIds);
+  const optionRows = [
+    ...choices.map((choice) => ({ kind: 'choice', ...choice })),
+    { kind: 'action', action: 'toggle-all', label: '[전체 선택/해제]' },
+    { kind: 'action', action: 'done', label: '[선택 완료]' }
+  ];
+  let cursor = 0;
+  let notice = '';
+
+  while (true) {
+    renderTuiHeader(title, help);
+    output.write(`선택됨: ${selected.size}개\n`);
+    if (notice) {
+      output.write(`알림: ${notice}\n`);
+    }
+    output.write('\n');
+
+    optionRows.forEach((row, index) => {
+      const pointer = index === cursor ? '>' : ' ';
+      if (row.kind === 'choice') {
+        output.write(`${formatTuiLine(pointer, row.label, selected.has(row.id))}\n`);
+        if (row.description) {
+          output.write(`    ${row.description}\n`);
+        }
+      } else {
+        output.write(`${pointer} ${row.label}\n`);
+      }
+    });
+
+    const { str, key } = await readKeypressOnce();
+    if (key.ctrl && key.name === 'c') {
+      throw new Error('사용자 취소');
+    }
+    if (str === 'q' || key.name === 'escape') {
+      throw new Error('사용자 취소');
+    }
+
+    const current = optionRows[cursor];
+    notice = '';
+
+    if (key.name === 'up') {
+      cursor = (cursor - 1 + optionRows.length) % optionRows.length;
+      continue;
+    }
+    if (key.name === 'down') {
+      cursor = (cursor + 1) % optionRows.length;
+      continue;
+    }
+
+    if (current.kind === 'choice' && (key.name === 'right' || str === ' ' || key.name === 'return' || key.name === 'enter')) {
+      if (selected.has(current.id)) {
+        selected.delete(current.id);
+      } else {
+        selected.add(current.id);
+      }
+      continue;
+    }
+
+    if (current.kind === 'choice' && key.name === 'left') {
+      selected.delete(current.id);
+      continue;
+    }
+
+    if (current.kind === 'action' && current.action === 'toggle-all' && (key.name === 'return' || key.name === 'enter' || key.name === 'right' || key.name === 'left')) {
+      if (selected.size === choices.length) {
+        selected.clear();
+      } else {
+        choices.forEach((choice) => selected.add(choice.id));
+      }
+      continue;
+    }
+
+    if (current.kind === 'action' && current.action === 'done' && (key.name === 'return' || key.name === 'enter' || key.name === 'right')) {
+      if (selected.size < minSelected) {
+        notice = `최소 ${minSelected}개 이상 선택해야 합니다.`;
+        continue;
+      }
+      return [...selected];
+    }
+  }
+}
+
+async function promptInteractiveTui({ catalog, mode, defaultTarget, presetFlag }) {
+  readline.emitKeypressEvents(input);
+  const wasRawMode = Boolean(input.isRaw);
+  setRawMode(true);
+  input.resume();
+
+  try {
+    const targetChoice = await runSingleSelectMenu({
+      title: `${CLI_NAME} 대화형 설정`,
+      help: '조작: 위/아래/좌/우 이동, Enter 선택, q 종료',
+      options: [
+        {
+          id: 'default',
+          label: `기본 경로 사용 (${defaultTarget})`,
+          description: '추천: 현재 실행 컨텍스트의 기본 경로를 그대로 사용'
+        },
+        {
+          id: 'cwd',
+          label: '현재 폴더(.) 사용',
+          description: '현재 터미널 위치를 바로 사용'
+        },
+        {
+          id: 'custom',
+          label: '직접 경로 입력',
+          description: '직접 절대/상대 경로를 입력'
+        }
+      ],
+      defaultIndex: 0
+    });
+
+    let targetInput = defaultTarget;
+    if (targetChoice.id === 'cwd') {
+      targetInput = '.';
+    } else if (targetChoice.id === 'custom') {
+      targetInput = await askLine('설치/업데이트 대상 경로를 입력하세요.', defaultTarget);
+    }
+
+    const targetDir = path.resolve(process.cwd(), targetInput);
+    const state = await readState(targetDir);
+    const presets = Array.isArray(catalog.presets) ? catalog.presets : [];
+
+    const defaultPresetId =
+      presetFlag ??
+      (mode === 'update' ? state?.preset_id : null) ??
+      (mode === 'install' ? presets[0]?.id ?? null : null);
+
+    const presetOptions = [
+      {
+        id: 'manual',
+        label: '수동 선택',
+        description: '프리셋 없이 도구/구성요소를 직접 선택'
+      },
+      ...presets.map((preset) => ({
+        id: preset.id,
+        label: `${preset.title} (${preset.id})`,
+        description: preset.description
+      }))
+    ];
+    const presetDefaultIndex =
+      defaultPresetId == null
+        ? 0
+        : Math.max(
+            0,
+            presetOptions.findIndex((option) => option.id === defaultPresetId)
+          );
+    const presetOption = await runSingleSelectMenu({
+      title: '프리셋 선택',
+      help: '조작: 위/아래/좌/우 이동, Enter 선택, q 종료',
+      options: presetOptions,
+      defaultIndex: presetDefaultIndex
+    });
+    const selectedPreset = presetOption.id === 'manual' ? null : findPreset(catalog, presetOption.id);
+
+    let defaultToolIds = catalog.ux_defaults?.recommended_tools ?? catalog.tools.map((t) => t.id);
+    const presetToolIds = resolveToolsFromPreset(selectedPreset, catalog);
+    if (presetToolIds.length > 0) {
+      defaultToolIds = presetToolIds;
+    } else if (mode === 'update' && state?.tools) {
+      const installed = Object.keys(state.tools);
+      if (installed.length > 0) {
+        defaultToolIds = installed;
+      }
+    }
+
+    const selectedToolIds = await runMultiSelectMenu({
+      title: '도구 선택',
+      help: '조작: 위/아래 이동, Space 토글, 좌(해제), 우(선택), Enter',
+      choices: catalog.tools.map((tool) => ({
+        id: tool.id,
+        label: `${tool.title} (${tool.id})`,
+        description: tool.description
+      })),
+      preselectedIds: defaultToolIds,
+      minSelected: 1
+    });
+
+    const componentSelection = {};
+    for (const toolId of selectedToolIds) {
+      const tool = findTool(catalog, toolId);
+      if (!tool) continue;
+
+      let defaultComponents = tool.components.map((c) => c.id);
+      const presetComponents = resolveComponentsFromPreset(tool, selectedPreset);
+      if (presetComponents.length > 0) {
+        defaultComponents = presetComponents;
+      } else if (mode === 'install') {
+        const recommended = catalog.ux_defaults?.recommended_components?.[tool.id];
+        if (Array.isArray(recommended) && recommended.length > 0) {
+          defaultComponents = recommended;
+        }
+      }
+      if (mode === 'update' && state?.tools?.[tool.id]?.components?.length) {
+        defaultComponents = state.tools[tool.id].components;
+      }
+
+      const selectedComponents = await runMultiSelectMenu({
+        title: `${tool.title} 구성요소 선택`,
+        help: '조작: 위/아래 이동, Space 토글, 좌(해제), 우(선택), Enter',
+        choices: tool.components.map((component) => ({
+          id: component.id,
+          label: `${component.title} (${component.id})`,
+          description: component.description
+        })),
+        preselectedIds: defaultComponents,
+        minSelected: 1
+      });
+      componentSelection[toolId] = selectedComponents;
+    }
+
+    return {
+      targetDir,
+      selectedToolIds,
+      componentSelection,
+      presetId: selectedPreset?.id ?? null
+    };
+  } finally {
+    setRawMode(wasRawMode);
+    clearTuiScreen();
+  }
+}
+
+async function promptInteractiveText({ catalog, mode, defaultTarget, presetFlag }) {
+  const rl = createInterface({ input, output });
+
+  const ask = async (question, defaultValue = '') => {
+    const suffix = defaultValue ? ` (기본: ${defaultValue})` : '';
+    const answer = await rl.question(`${question}${suffix}\n> `);
+    return answer.trim() || defaultValue;
+  };
+
+  try {
+    console.log('');
+    console.log(`=== ${CLI_NAME} 대화형 설치/업데이트(텍스트 모드) ===`);
+    console.log('숫자 또는 ID를 콤마로 입력하세요. 예: 1,3 또는 codex,claude-code');
+    console.log('중복 입력은 자동으로 정리됩니다.');
+
+    const targetInput = await ask('설치/업데이트 대상 경로를 입력하세요.', defaultTarget);
+    const targetDir = path.resolve(process.cwd(), targetInput);
+    const state = await readState(targetDir);
+
+    const presets = Array.isArray(catalog.presets) ? catalog.presets : [];
+    let selectedPreset = findPreset(catalog, presetFlag);
+    if (!selectedPreset && presets.length > 0) {
+      console.log('');
+      console.log('[프리셋 목록]');
+      console.log('0. 수동 선택');
+      presets.forEach((preset, index) => {
+        console.log(`${index + 1}. ${preset.title} (${preset.id})`);
+        console.log(`   - ${preset.description}`);
+      });
+
+      const defaultPresetId = mode === 'install' ? presets[0]?.id ?? '0' : '0';
+      const presetAnswer = await ask(
+        '프리셋을 선택하세요. (번호/ID, 수동 선택은 0)',
+        defaultPresetId
+      );
+      selectedPreset = resolvePresetFromInput(presetAnswer, catalog, defaultPresetId);
+    }
+
+    console.log('');
+    console.log('[도구 목록]');
+    catalog.tools.forEach((tool, index) => {
+      console.log(`${index + 1}. ${tool.title} (${tool.id})`);
+      console.log(`   - ${tool.description}`);
+    });
+
+    let defaultToolIds = catalog.ux_defaults?.recommended_tools ?? catalog.tools.map((t) => t.id);
+    const presetToolIds = resolveToolsFromPreset(selectedPreset, catalog);
+    if (presetToolIds.length > 0) {
+      defaultToolIds = presetToolIds;
+    } else if (mode === 'update' && state?.tools) {
+      const installed = Object.keys(state.tools);
+      if (installed.length > 0) {
+        defaultToolIds = installed;
+      }
+    }
+
+    const toolAnswer = await ask(
+      '작업할 도구를 선택하세요. (`all` 가능)',
+      defaultToolIds.join(',')
+    );
+    const selectedToolIds = parseChoiceInput(toolAnswer, catalog.tools, defaultToolIds);
+
+    const componentSelection = {};
+    for (const toolId of selectedToolIds) {
+      const tool = findTool(catalog, toolId);
+      if (!tool) continue;
+
+      console.log('');
+      console.log(`[${tool.title}] 구성요소 목록`);
+      tool.components.forEach((component, index) => {
+        console.log(`${index + 1}. ${component.title} (${component.id})`);
+        console.log(`   - ${component.description}`);
+      });
+
+      let defaultComponents = tool.components.map((c) => c.id);
+      const presetComponents = resolveComponentsFromPreset(tool, selectedPreset);
+      if (presetComponents.length > 0) {
+        defaultComponents = presetComponents;
+      } else if (mode === 'install') {
+        const recommended = catalog.ux_defaults?.recommended_components?.[tool.id];
+        if (Array.isArray(recommended) && recommended.length > 0) {
+          defaultComponents = recommended;
+        }
+      }
+      if (mode === 'update' && state?.tools?.[tool.id]?.components?.length) {
+        defaultComponents = state.tools[tool.id].components;
+      }
+
+      const componentAnswer = await ask(
+        `${tool.id}에서 설치/업데이트할 구성요소를 선택하세요. (` + '`all` 가능)',
+        defaultComponents.join(',')
+      );
+      componentSelection[tool.id] = parseChoiceInput(
+        componentAnswer,
+        tool.components,
+        defaultComponents
+      );
+    }
+
+    return {
+      targetDir,
+      selectedToolIds,
+      componentSelection,
+      presetId: selectedPreset?.id ?? null
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptInteractive(params) {
+  if (input.isTTY && output.isTTY) {
+    return promptInteractiveTui(params);
+  }
+  return promptInteractiveText(params);
+}
+
+function buildSelectionFromFlags({
+  catalog,
+  mode,
+  presetFlag,
+  toolFlag,
+  componentFlag,
+  targetFlag
+}) {
+  const preset = findPreset(catalog, presetFlag);
+  const presetToolIds = resolveToolsFromPreset(preset, catalog);
+  const selectedToolIds = toolFlag
+    ? resolveToolsFromFlag(toolFlag, catalog)
+    : presetToolIds.length > 0
+      ? presetToolIds
+      : resolveToolsFromFlag(undefined, catalog);
+  const componentSelection = {};
+
+  for (const toolId of selectedToolIds) {
+    const tool = findTool(catalog, toolId);
+    if (!tool) {
+      throw new Error(`카탈로그에 없는 tool: ${toolId}`);
+    }
+
+    if (componentFlag) {
+      componentSelection[toolId] = resolveComponentsFromFlag(componentFlag, tool, mode);
+      continue;
+    }
+
+    const presetComponents = resolveComponentsFromPreset(tool, preset);
+    if (presetComponents.length > 0) {
+      componentSelection[toolId] = presetComponents;
+      continue;
+    }
+
+    componentSelection[toolId] = resolveComponentsFromFlag(undefined, tool, mode);
+  }
+
+  return {
+    targetDir: path.resolve(process.cwd(), targetFlag),
+    selectedToolIds,
+    componentSelection,
+    presetId: preset?.id ?? null
+  };
+}
+
+async function copyEntry(srcPath, destPath, { overwrite, dryRun }) {
+  const srcStat = await fs.stat(srcPath);
+  const destExists = await exists(destPath);
+
+  if (destExists && !overwrite) {
+    return { status: 'skipped' };
+  }
+
+  if (dryRun) {
+    return { status: destExists ? 'would-overwrite' : 'would-copy' };
+  }
+
+  if (srcStat.isDirectory()) {
+    await fs.cp(srcPath, destPath, { recursive: true, force: overwrite });
+  } else {
+    await fs.mkdir(path.dirname(destPath), { recursive: true });
+    await fs.copyFile(srcPath, destPath);
+  }
+
+  return { status: destExists ? 'overwritten' : 'copied' };
+}
+
+function statusLabel(status) {
+  switch (status) {
+    case 'copied':
+      return '복사';
+    case 'overwritten':
+      return '업데이트';
+    case 'skipped':
+      return '건너뜀';
+    case 'would-copy':
+      return '복사 예정';
+    case 'would-overwrite':
+      return '업데이트 예정';
+    default:
+      return status;
+  }
+}
+
+function printPlan(catalog, selection, mode, targetDir) {
+  console.log('');
+  console.log('실행 계획');
+  console.log(`- 모드: ${mode}`);
+  console.log(`- 프리셋: ${selection.presetId ?? '수동/없음'}`);
+  console.log(`- 대상 경로: ${targetDir}`);
+
+  for (const toolId of selection.selectedToolIds) {
+    const tool = findTool(catalog, toolId);
+    const componentIds = selection.componentSelection[toolId] ?? [];
+    const labels = tool.components
+      .filter((c) => componentIds.includes(c.id))
+      .map((c) => `${c.title}(${c.id})`)
+      .join(', ');
+    console.log(`- ${tool.title}(${tool.id}): ${labels || '선택된 항목 없음'}`);
+  }
+}
+
+async function confirmProceed(yesFlag) {
+  if (yesFlag) return true;
+  if (!process.stdin.isTTY) return true;
+
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question('계속 진행할까요? (y/N)\n> ');
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+async function readState(targetDir) {
+  const statePath = path.join(targetDir, STATE_DIR_NAME, 'state.json');
+  if (await exists(statePath)) {
+    try {
+      return await readJson(statePath);
+    } catch {
+      return null;
+    }
+  }
+
+  const legacyStatePath = path.join(targetDir, LEGACY_STATE_DIR_NAME, 'state.json');
+  if (await exists(legacyStatePath)) {
+    try {
+      return await readJson(legacyStatePath);
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+async function writeState({ targetDir, packageData, mode, selection }) {
+  const stateDir = path.join(targetDir, STATE_DIR_NAME);
+  const statePath = path.join(stateDir, 'state.json');
+
+  const tools = {};
+  for (const toolId of selection.selectedToolIds) {
+    tools[toolId] = {
+      components: selection.componentSelection[toolId] ?? [],
+      last_mode: mode
+    };
+  }
+
+  const statePayload = {
+    schema_version: '1.0.0',
+    package_name: packageData.name,
+    package_version: packageData.version,
+    updated_at: new Date().toISOString(),
+    preset_id: selection.presetId ?? null,
+    tools
+  };
+
+  await fs.mkdir(stateDir, { recursive: true });
+  await fs.writeFile(statePath, `${JSON.stringify(statePayload, null, 2)}\n`, 'utf8');
+}
+
+async function runInstallOrUpdate({ catalog, packageData, mode, selection, force, dryRun }) {
+  const overwrite = mode === 'update' || force;
+  const targetDir = selection.targetDir;
+  await fs.mkdir(targetDir, { recursive: true });
+
+  const results = [];
+
+  for (const toolId of selection.selectedToolIds) {
+    const tool = findTool(catalog, toolId);
+    if (!tool) {
+      throw new Error(`카탈로그에 없는 tool: ${toolId}`);
+    }
+
+    const toolDestRoot = path.join(targetDir, tool.root);
+    await fs.mkdir(toolDestRoot, { recursive: true });
+
+    const readmeSrc = path.join(rootDir, tool.root, tool.readme);
+    const readmeDst = path.join(toolDestRoot, tool.readme);
+    const readmeResult = await copyEntry(readmeSrc, readmeDst, { overwrite, dryRun });
+    results.push({
+      toolId,
+      entry: `${tool.root}/${tool.readme}`,
+      status: readmeResult.status
+    });
+
+    const componentIds = selection.componentSelection[toolId] ?? [];
+    for (const componentId of componentIds) {
+      const component = tool.components.find((c) => c.id === componentId);
+      if (!component) {
+        throw new Error(`[${tool.id}] 알 수 없는 구성요소: ${componentId}`);
+      }
+
+      const src = path.join(rootDir, tool.root, component.path);
+      const dst = path.join(targetDir, tool.root, component.path);
+      const result = await copyEntry(src, dst, { overwrite, dryRun });
+      results.push({
+        toolId,
+        entry: `${tool.root}/${component.path}`,
+        status: result.status
+      });
+    }
+  }
+
+  console.log('');
+  console.log('적용 결과');
+  for (const item of results) {
+    console.log(`- [${item.toolId}] ${item.entry}: ${statusLabel(item.status)}`);
+  }
+
+  if (!dryRun) {
+    await writeState({ targetDir, packageData, mode, selection });
+    console.log('');
+    console.log(`상태 파일 저장: ${path.join(targetDir, STATE_DIR_NAME, 'state.json')}`);
+  }
+}
+
+function printList(catalog) {
+  console.log('');
+  console.log(`${CLI_NAME} 카탈로그 (한글)`);
+  console.log('');
+  for (const tool of catalog.tools) {
+    console.log(`- ${tool.title} (${tool.id})`);
+    console.log(`  설명: ${tool.description}`);
+    console.log('  구성요소:');
+    for (const component of tool.components) {
+      console.log(`  - ${component.title} (${component.id}): ${component.description}`);
+    }
+    console.log('');
+  }
+
+  const presets = Array.isArray(catalog.presets) ? catalog.presets : [];
+  if (presets.length > 0) {
+    console.log('프리셋 목록');
+    for (const preset of presets) {
+      console.log(`- ${preset.title} (${preset.id})`);
+      console.log(`  설명: ${preset.description}`);
+    }
+    console.log('');
+  }
+
+  console.log('권장 UX 흐름');
+  console.log('1) pnpm dlx tri-agent-manager --interactive 로 시작합니다.');
+  console.log('2) 설치 후 state.json을 기준으로 update를 수행한다.');
+  console.log('3) update 시 필요한 도구만 부분 갱신한다.');
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+    console.log(HELP_TEXT);
+    return;
+  }
+
+  const options = parseArgs(rawArgs);
+  let command = options.command;
+  if (command === 'setup' || command === 'wizard') {
+    options.interactive = true;
+    command = 'install';
+  }
+  if (command === 'init') {
+    command = 'install';
+  }
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(HELP_TEXT);
+    return;
+  }
+
+  const catalog = await readJson(catalogPath);
+  const packageData = await readJson(packageJsonPath);
+
+  if (command === 'list') {
+    printList(catalog);
+    return;
+  }
+
+  if (command !== 'install' && command !== 'update') {
+    console.error(`지원하지 않는 명령: ${command}`);
+    console.error('');
+    console.error(HELP_TEXT);
+    process.exit(1);
+  }
+
+  const shouldUseInteractive =
+    !options.nonInteractive &&
+    (options.interactive || (!options.toolFlag && !options.presetFlag && process.stdin.isTTY));
+
+  const selection = shouldUseInteractive
+    ? await promptInteractive({
+        catalog,
+        mode: command,
+        defaultTarget: options.targetFlag,
+        presetFlag: options.presetFlag
+      })
+    : buildSelectionFromFlags({
+        catalog,
+        mode: command,
+        presetFlag: options.presetFlag,
+        toolFlag: options.toolFlag,
+        componentFlag: options.componentFlag,
+        targetFlag: options.targetFlag
+      });
+
+  printPlan(catalog, selection, command, selection.targetDir);
+
+  const proceed = await confirmProceed(options.yes);
+  if (!proceed) {
+    console.log('작업을 취소했습니다.');
+    return;
+  }
+
+  await runInstallOrUpdate({
+    catalog,
+    packageData,
+    mode: command,
+    selection,
+    force: options.force,
+    dryRun: options.dryRun
+  });
+
+  console.log('');
+  console.log('완료: 선택한 운영팩 반영이 끝났습니다.');
+}
+
+main().catch((error) => {
+  console.error(`오류: ${error.message}`);
+  process.exit(1);
+});