jutell 0.3.0

package/dist/cli.js

@@ -0,0 +1,82 @@
+import { resolveScope } from './config/paths.js';
+import { readVersionInfo } from './config/managed.js';
+import { parseOptions, createIo, printHelp } from './output/format.js';
+import { setupCommand, enableCommand, disableCommand, uninstallCommand } from './commands/lifecycle.js';
+import { statusCommand, doctorCommand } from './commands/status.js';
+import { dashboardCommand } from './commands/dashboard.js';
+import { defaultCommand } from './commands/default.js';
+import { onCommand, offCommand } from './commands/lifecycle.js';
+import { providerCommand } from './commands/provider.js';
+import { useCommand, connectCommand, disconnectCommand, switchCommand } from './commands/use.js';
+import { sessionCommand } from './commands/session/index.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { migrateCommand } from './commands/migrate.js';
+function safeError(message, verbose) {
+    if (verbose)
+        return message;
+    if (/ENOENT|EACCES|EPERM|spawn EINVAL/i.test(message))
+        return '필요한 파일이나 실행 권한을 확인하지 못했습니다. `jutell doctor`를 실행해 주세요.';
+    return message.replace(/[A-Za-z]:[\\/][^\r\n'" ]+/g, '[경로]');
+}
+export async function run(argv = process.argv.slice(2), io = createIo(), legacyAlias = false) {
+    if (legacyAlias)
+        io.write('`beginner-bridge`는 이전 명령입니다. 앞으로는 `jutell` 사용을 권장합니다.');
+    if (argv.includes('--version')) {
+        io.write((await readVersionInfo()).cli);
+        return 0;
+    }
+    try {
+        const { command, options, defaultInvocation, extraArgs } = parseOptions(argv);
+        if (command === 'help') {
+            printHelp(io);
+            return 0;
+        }
+        const paths = resolveScope(options.scope);
+        if (options.statusOnly)
+            await statusCommand(paths, options, io);
+        else if (defaultInvocation)
+            await defaultCommand(paths, options, io);
+        else if (command === 'setup')
+            await setupCommand(paths, options, io);
+        else if (command === 'dashboard')
+            await dashboardCommand(paths, options, io);
+        else if (command === 'on')
+            await onCommand(paths, options, io);
+        else if (command === 'off')
+            await offCommand(paths, options, io);
+        else if (command === 'status')
+            await statusCommand(paths, options, io);
+        else if (command === 'enable')
+            await enableCommand(paths, options, io);
+        else if (command === 'disable')
+            await disableCommand(paths, options, io);
+        else if (command === 'doctor')
+            await doctorCommand(paths, options, io);
+        else if (command === 'uninstall')
+            await uninstallCommand(paths, options, io);
+        else if (command === 'provider')
+            await providerCommand(paths, options, io, extraArgs);
+        else if (command === 'use')
+            await useCommand(paths, options, io, [command, ...extraArgs]);
+        else if (command === 'connect')
+            await connectCommand(paths, options, io, [command, ...extraArgs]);
+        else if (command === 'disconnect')
+            await disconnectCommand(paths, options, io, [command, ...extraArgs]);
+        else if (command === 'switch')
+            await switchCommand(paths, options, io, [command, ...extraArgs]);
+        else if (command === 'upgrade')
+            await upgradeCommand(paths, options, io);
+        else if (command === 'migrate')
+            await migrateCommand(paths, options, io);
+        else if (command === 'session')
+            await sessionCommand(paths, options, io, extraArgs);
+        else
+            throw new Error(`알 수 없는 명령입니다: ${command}`);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '작업을 처리하지 못했습니다.';
+        io.error(`오류: ${safeError(message, argv.includes('--verbose'))}`);
+        return 1;
+    }
+}

package/dist/commands/dashboard.js

@@ -0,0 +1,81 @@
+import { promises as fs } from 'node:fs';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assets } from '../config/paths.js';
+import { exists } from '../config/managed.js';
+import { openBrowser } from '../process/system.js';
+const contentTypes = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8', '.svg': 'image/svg+xml' };
+async function readMarker(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function alive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function serveStatic(req, res, root) {
+    const requestPath = decodeURIComponent(new URL(req.url ?? '/', 'http://127.0.0.1').pathname);
+    const relative = requestPath === '/' ? 'index.html' : requestPath.replace(/^\/+/, '');
+    if (!relative || relative.includes('..')) {
+        res.statusCode = 400;
+        res.end('잘못된 요청입니다.');
+        return;
+    }
+    const file = path.join(root, relative);
+    if (!(await exists(file))) {
+        res.statusCode = 404;
+        res.end('파일을 찾을 수 없습니다.');
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader('Content-Type', contentTypes[path.extname(file).toLowerCase()] ?? 'application/octet-stream');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(await fs.readFile(file));
+}
+export async function dashboardCommand(paths, options, io) {
+    const marker = path.join(paths.dataRoot, 'dashboard.json');
+    const existing = await readMarker(marker);
+    if (existing && await alive(existing.pid)) {
+        const url = `http://127.0.0.1:${existing.port}`;
+        io.write(`로컬 관리자 화면이 이미 실행 중입니다.\n${url}`);
+        if (options.openBrowser)
+            await openBrowser(url, io);
+        return { started: false, url };
+    }
+    await fs.rm(marker, { force: true });
+    process.env.BEGINNER_BRIDGE_MCP_SERVER = path.join(assets().mcpServer, 'index.js');
+    process.env.JUTELL_TEMPLATES_ROOT = path.join(assets().root, 'templates', 'request-builder');
+    const module = await import(pathToFileURL(assets().localAdminServer).href);
+    const server = createServer((req, res) => {
+        if ((req.url ?? '/').startsWith('/api/'))
+            void module.handleApiRequest(req, res, paths.targetRoot);
+        else
+            void serveStatic(req, res, assets().localAdmin);
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', () => { server.off('error', reject); resolve(); }); });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : 0;
+    await fs.mkdir(paths.dataRoot, { recursive: true });
+    await fs.writeFile(marker, `${JSON.stringify({ pid: process.pid, port })}\n`, 'utf8');
+    const url = `http://127.0.0.1:${port}`;
+    io.write(`JuTell 로컬 관리자를 실행했습니다.\n${url}\n종료하려면 이 터미널에서 Ctrl+C를 누르세요.`);
+    if (options.openBrowser)
+        await openBrowser(url, io);
+    const close = async () => { await fs.rm(marker, { force: true }); server.close(); };
+    process.once('SIGINT', () => void close().then(() => process.exit(0)));
+    process.once('SIGTERM', () => void close().then(() => process.exit(0)));
+    await new Promise((resolve) => server.once('close', resolve));
+    return { started: true, url };
+}

package/dist/commands/default.js

@@ -0,0 +1,103 @@
+import { stdin } from 'node:process';
+import { dashboardCommand } from './dashboard.js';
+import { enableCommand, setupCommand } from './lifecycle.js';
+import { getStatus } from './status.js';
+import { useCommand } from './use.js';
+import { AGENT_PROVIDERS } from '../installer/providers.js';
+const profileLabels = {
+    minimal: '최소 보고',
+    balanced: '균형 보고',
+    learning: '학습 보고',
+    detailed: '상세 보고',
+};
+const profileChoices = [
+    { value: 'balanced', label: '균형 보고', note: '처음 사용에 적당한 기본값 (권장)' },
+    { value: 'minimal', label: '최소 보고', note: '핵심만 짧게' },
+    { value: 'learning', label: '학습 보고', note: '개발 용어를 조금 더 설명' },
+    { value: 'detailed', label: '상세 보고', note: '복잡한 작업을 자세히' },
+];
+function needsRepair(status) {
+    return !status.configValid || !status.skillInstalled || !status.agentsManaged || status.codexPreparation !== 'enabled';
+}
+function readyMessage(status) {
+    const ready = status.configValid && status.skillInstalled && status.agentsManaged && status.codexPreparation === 'enabled';
+    if (!ready) {
+        return `JuTell 연결이 일부 준비되지 않았습니다.
+
+설정과 Skill을 확인했지만 AI Agent Provider 연결 준비가 완료되지 않았습니다.
+관리자 화면에서 현재 상태를 확인할 수 있습니다.`;
+    }
+    return `JuTell 준비 완료
+
+✓ 설정 연결됨
+✓ Skill 연결됨
+✓ AI Agent 연결 준비 완료
+✓ 안전 보고 규칙 적용됨
+
+현재 보고 방식: ${profileLabels[status.profile]}
+활성 기능: ${status.activeFeatureCount}개
+
+새 AI Agent 세션부터 사용할 수 있습니다.
+실제 도구 호출 여부는 해당 Provider에서 확인할 수 있습니다.`;
+}
+const firstRunMessage = `이 프로젝트에는 아직 JuTell이 연결되지 않았습니다.
+
+JuTell을 연결하면:
+- AI 작업을 쉬운 말로 보고받을 수 있습니다.
+- 현재 설정에 맞춰 보고 길이와 설명 방식을 조절할 수 있습니다.
+- 연결된 AI Agent에서 JuTell MCP를 사용할 수 있습니다.`;
+async function firstRunWizard(io) {
+    io.write(`Welcome to JuTell! 🎉
+
+AI가 한 일을 쉽게 이해하고, 검증하고, 다음 작업으로 이어가도록 돕습니다.
+몇 가지만 고르면 이 프로젝트에 연결을 준비합니다.
+`);
+    const agentChoices = AGENT_PROVIDERS.map((provider) => ({
+        value: provider.id,
+        label: provider.label,
+        note: provider.status === 'planned' ? '준비 중' : provider.description,
+    }));
+    let agent = 'codex';
+    while (true) {
+        const picked = await io.choose('① 사용 중인 AI Agent를 선택하세요.', agentChoices, 'codex');
+        const provider = AGENT_PROVIDERS.find((item) => item.id === picked);
+        if (provider && provider.status !== 'planned') {
+            agent = provider.id;
+            break;
+        }
+        io.write(`${provider?.label ?? '선택한 Agent'}는 아직 준비 중입니다. 지금 사용할 수 있는 Agent를 선택하세요.`);
+    }
+    const profile = (await io.choose('② 보고 방식을 선택하세요. 나중에 언제든 바꿀 수 있습니다.', profileChoices, 'balanced'));
+    const agentLabel = AGENT_PROVIDERS.find((item) => item.id === agent)?.label ?? agent;
+    io.write(`\n③ 선택 완료: ${agentLabel} · ${profileLabels[profile]}\n연결을 준비합니다.\n`);
+    return { agent, profile };
+}
+export async function defaultCommand(paths, options, io) {
+    let status = await getStatus(paths);
+    if (!status.configExists) {
+        if (options.yes || stdin.isTTY !== true) {
+            io.write(firstRunMessage);
+            if (!options.yes && !(await io.ask('이 프로젝트에 연결할까요?', true))) {
+                io.write('JuTell을 연결하지 않았습니다.');
+                return { cancelled: true };
+            }
+            await setupCommand(paths, { ...options, yes: true, oneCommand: true, activateMcp: true }, io);
+        }
+        else {
+            const picked = await firstRunWizard(io);
+            await useCommand(paths, { ...options, yes: true, profile: picked.profile }, io, ['use', picked.agent]);
+        }
+    }
+    else if (needsRepair(status)) {
+        io.write('JuTell 연결이 일부 준비되지 않았습니다.\nSkill, AGENTS.md, AI Agent Provider 연결 준비를 안전하게 확인할 수 있습니다.');
+        if (!options.yes && !(await io.ask('다시 켜고 관리자 화면을 열까요?', true))) {
+            io.write('현재 설정을 그대로 두고 관리자 화면을 엽니다.');
+        }
+        else {
+            await enableCommand(paths, { ...options, yes: true, oneCommand: true }, io);
+        }
+    }
+    status = await getStatus(paths);
+    io.write(readyMessage(status));
+    return dashboardCommand(paths, options, io);
+}

package/dist/commands/lifecycle.js

@@ -0,0 +1,166 @@
+import { promises as fs } from 'node:fs';
+import { assets, codexScopedPaths, packageRoot, safeLocation } from '../config/paths.js';
+import { readBridgeConfig, snapshot, restore } from '../config/managed.js';
+import { ensureBridgeConfig, setMcpDisabled, setMcpEnabled } from '../installer/config.js';
+import { installSkill, recordSkillFiles, removeAddedSkillFiles, removeManagedSkillFiles } from '../installer/skill.js';
+import { agentsFile, ensureJuTellAgentsBlock, removeJuTellAgentsBlock } from '../installer/agents.js';
+import { registerMcp, removeMcp } from '../config/managed.js';
+import { removeOpenCodeMcp, readOpenCodeRegistration, setOpenCodeEnabled } from '../installer/opencode.js';
+import { removeClaudeMcp } from '../installer/claude.js';
+import { scopeLabel } from '../output/format.js';
+import { codexDetected, nodeMajorVersion, operatingSystem } from '../process/system.js';
+function validProfile(value) {
+    return !value || ['minimal', 'balanced', 'learning', 'detailed'].includes(value);
+}
+export async function setupCommand(paths, options, io) {
+    if (!validProfile(options.profile))
+        throw new Error('Profile은 minimal, balanced, learning, detailed 중 하나여야 합니다.');
+    const currentConfig = await readBridgeConfig(paths);
+    const plannedProfile = options.profile ?? currentConfig.config.profile;
+    const migrationNote = currentConfig.source === 'legacy' ? '\n기존 설정을 읽었습니다. 승인하면 .jutell.json을 만들고 기존 파일은 보존합니다.\n' : '';
+    if (!options.oneCommand)
+        io.write(`JuTell 설치 미리보기\n${migrationNote}\n\n운영체제: ${operatingSystem()}\nNode: ${process.versions.node} (${nodeMajorVersion() >= 18 ? '지원 범위' : '낮은 버전'})\nAI Agent Provider 감지: ${codexDetected() ? '현재 지원 Provider 확인' : '직접 확인 필요'}\n설치 범위: ${scopeLabel(paths.scope)}\nProfile: ${plannedProfile}\nSkill: ${options.mcpOnly ? '변경하지 않음' : '설치 또는 기존 파일 유지'}\nMCP: ${options.skillOnly ? '변경하지 않음' : '기존 설정을 보존하고 관리 블록 등록'}\n기본 자동 시작: OFF\n`);
+    if (!options.yes && !(await io.ask('위 변경을 진행할까요?')))
+        return { cancelled: true };
+    const configSnapshot = await snapshot(paths.configFile);
+    const codexSnapshot = await snapshot(codexScopedPaths(paths).codexConfigFile);
+    const agentsSnapshot = paths.scope === 'project' ? await snapshot(agentsFile(paths.targetRoot)) : undefined;
+    let skillResult = { conflicts: [], changed: [] };
+    try {
+        skillResult = options.mcpOnly ? { conflicts: [], changed: [] } : await installSkill(assets().skill, paths.skillRoot);
+        const ensured = await ensureBridgeConfig(paths, options.profile);
+        if (paths.scope === 'project' && !options.mcpOnly)
+            await ensureJuTellAgentsBlock(paths.targetRoot);
+        if (!options.skillOnly) {
+            if (options.activateMcp)
+                await setMcpEnabled(paths, true);
+            // Codex only reads MCP servers from its global config, so registration
+            // always targets that file regardless of --project/--global (see
+            // codexScopedPaths). .jutell.json/Skill/AGENTS.md above stay scoped
+            // to what the user requested.
+            await registerMcp(codexScopedPaths(paths), packageRoot(), options.activateMcp || ensured.config.mcp?.enabled === true);
+        }
+        await recordSkillFiles(paths, skillResult.changed);
+        if (!options.oneCommand) {
+            io.write(`설치가 완료되었습니다.\n\n설치 범위: ${scopeLabel(paths.scope)}\nProfile: ${ensured.config.profile}\nSkill: ${skillResult.conflicts.length ? '충돌 파일을 보존함' : '설치됨'}\nMCP: ${options.skillOnly ? '변경하지 않음' : `등록됨 (${options.activateMcp ? '활성화' : '기본 활성화: 꺼짐'})`}\n설정: ${safeLocation(paths.scope, 'config')}${options.skillOnly ? '' : `\nCodex MCP: ${safeLocation(paths.scope, 'codex')} (Codex는 전역 설정만 읽습니다)`}\n\n다음 실행: jutell`);
+            if (skillResult.conflicts.length)
+                io.write(`\n주의: 기존 파일을 덮어쓰지 않았습니다: ${skillResult.conflicts.join(', ')}`);
+        }
+        return { cancelled: false, skillResult };
+    }
+    catch (error) {
+        await restore(configSnapshot);
+        await restore(codexSnapshot);
+        if (agentsSnapshot)
+            await restore(agentsSnapshot);
+        await removeAddedSkillFiles(paths.skillRoot, skillResult.changed);
+        throw error;
+    }
+}
+export async function enableCommand(paths, options, io) {
+    if (!options.yes && !(await io.ask(`JuTell을 ${scopeLabel(paths.scope)}에서 활성화할까요?`)))
+        return { cancelled: true };
+    const configSnapshot = await snapshot(paths.configFile);
+    const codexSnapshot = await snapshot(codexScopedPaths(paths).codexConfigFile);
+    const agentsSnapshot = paths.scope === 'project' ? await snapshot(agentsFile(paths.targetRoot)) : undefined;
+    let skillResult = { conflicts: [], changed: [] };
+    try {
+        skillResult = options.mcpOnly ? { conflicts: [], changed: [] } : await installSkill(assets().skill, paths.skillRoot);
+        const config = await ensureBridgeConfig(paths, undefined);
+        if (paths.scope === 'project' && !options.mcpOnly)
+            await ensureJuTellAgentsBlock(paths.targetRoot);
+        if (!options.skillOnly) {
+            const enabled = await setMcpEnabled(paths, true);
+            // Codex MCP registration always targets the global config (see codexScopedPaths).
+            await registerMcp(codexScopedPaths(paths), packageRoot(), enabled.mcp?.enabled === true);
+            const opencode = await readOpenCodeRegistration(paths, packageRoot(), enabled.mcp?.enabled === true);
+            if (opencode.registered)
+                await setOpenCodeEnabled(paths, packageRoot(), true);
+        }
+        await recordSkillFiles(paths, skillResult.changed);
+        if (!options.oneCommand) {
+            io.write(`활성화했습니다. Skill: ${options.mcpOnly ? '변경하지 않음' : '사용 가능'}, MCP: ${options.skillOnly ? '변경하지 않음' : '활성화됨'}.`);
+            if (!options.skillOnly)
+                io.write('새 AI Agent 세션 또는 재시작이 필요할 수 있습니다.');
+            if (skillResult.conflicts.length)
+                io.write(`주의: 기존 Skill 파일은 덮어쓰지 않았습니다: ${skillResult.conflicts.join(', ')}`);
+        }
+        return { cancelled: false, config };
+    }
+    catch (error) {
+        await restore(configSnapshot);
+        await restore(codexSnapshot);
+        if (agentsSnapshot)
+            await restore(agentsSnapshot);
+        await removeAddedSkillFiles(paths.skillRoot, skillResult.changed);
+        throw error;
+    }
+}
+export async function disableCommand(paths, options, io) {
+    const disableSkill = options.disableSkill;
+    const disableMcp = options.disableMcp || (!disableSkill && !options.disableAll);
+    if (!options.yes && !(await io.ask(`JuTell 연결을 ${scopeLabel(paths.scope)}에서 비활성화할까요?`)))
+        return { cancelled: true };
+    let codexSkipped = false;
+    if (disableMcp) {
+        const config = await setMcpDisabled(paths);
+        // Codex MCP registration is a single global entry shared by every
+        // project on this machine (see codexScopedPaths). A project-scoped
+        // disable only turns off *this project's* connection policy; it does
+        // not reach into that shared global entry unless the user explicitly
+        // asked for --global, so other projects using Codex + JuTell keep working.
+        if (paths.scope === 'global')
+            await registerMcp(codexScopedPaths(paths), packageRoot(), config.mcp?.enabled === true);
+        else
+            codexSkipped = true;
+        await setOpenCodeEnabled(paths, packageRoot(), false);
+        // Claude's own local/project scope is already correctly per-project
+        // (unlike Codex's forced-global registration), so removing it here has
+        // no cross-project blast radius - safe to always do, no scope gate needed.
+        await removeClaudeMcp(paths, packageRoot());
+    }
+    if (disableSkill)
+        await removeManagedSkillFiles(assets().skill, paths.skillRoot, paths);
+    if (disableSkill && paths.scope === 'project')
+        await removeJuTellAgentsBlock(paths.targetRoot);
+    io.write(`비활성화했습니다. Skill: ${disableSkill ? '비활성화됨' : '유지됨'}, MCP: ${disableMcp ? '비활성화됨' : '유지됨'}.`);
+    io.write('설정과 Beta Journal 데이터는 보존했습니다.');
+    if (codexSkipped)
+        io.write('Codex MCP 연결(전역 설정)은 다른 프로젝트와 공유되어 그대로 두었습니다. 모든 프로젝트에서 끄려면 jutell disable --global 을 실행하세요.');
+    return { cancelled: false };
+}
+export async function uninstallCommand(paths, options, io) {
+    const removeData = options.removeData;
+    const dataMessage = removeData ? '설정과 Beta Journal도 삭제합니다.' : '설정과 Beta Journal은 보존합니다.';
+    if (!options.yes && !(await io.ask(`JuTell을 제거할까요? ${dataMessage}`)))
+        return { cancelled: true };
+    // Codex MCP registration is a single global entry shared by every project
+    // on this machine (see codexScopedPaths). Removing JuTell from one project
+    // must not silently break that shared connection for other projects, so a
+    // project-scoped uninstall leaves it in place unless the user asked for
+    // --global.
+    const codexSkipped = paths.scope !== 'global';
+    if (!codexSkipped)
+        await removeMcp(codexScopedPaths(paths), packageRoot());
+    await removeManagedSkillFiles(assets().skill, paths.skillRoot, paths);
+    if (paths.scope === 'project')
+        await removeJuTellAgentsBlock(paths.targetRoot);
+    await removeOpenCodeMcp(paths, packageRoot());
+    // Same reasoning as disable: Claude's scope is already per-project, so no
+    // shared-global-entry risk to guard against here.
+    await removeClaudeMcp(paths, packageRoot());
+    if (removeData) {
+        await fs.rm(paths.configFile, { force: true });
+        await fs.rm(paths.dataRoot, { recursive: true, force: true });
+    }
+    io.write(`제거했습니다. ${removeData ? '설정과 Beta Journal도 삭제했습니다.' : '설정과 Beta Journal은 보존했습니다.'}`);
+    if (codexSkipped)
+        io.write('Codex MCP 연결(전역 설정)은 다른 프로젝트와 공유되어 제거하지 않았습니다. 모든 프로젝트에서 제거하려면 jutell uninstall --global 을 실행하세요.');
+    return { cancelled: false };
+}
+export async function onCommand(paths, options, io) {
+    return enableCommand(paths, { ...options, skillOnly: false, mcpOnly: false }, io);
+}
+export async function offCommand(paths, options, io) {
+    return disableCommand(paths, { ...options, disableSkill: true, disableMcp: true, disableAll: true }, io);
+}

package/dist/commands/migrate.js

@@ -0,0 +1,159 @@
+import { promises as fs } from 'node:fs';
+import { codexScopedPaths, packageRoot } from '../config/paths.js';
+import { readBridgeConfig, readCodexRegistration, readText, writeTextSafely } from '../config/managed.js';
+import { ensureBridgeConfig } from '../installer/config.js';
+import { readOpenCodeRegistration, registerOpenCodeMcp } from '../installer/opencode.js';
+import { readClaudeRegistration } from '../installer/claude.js';
+import { registerMcp } from '../config/managed.js';
+export async function migrateCommand(paths, options, io) {
+    const clean = Boolean(options.clean || options.cleanLegacy || options.removeData);
+    const beforeConfig = await readBridgeConfig(paths);
+    const codexReg = await readCodexRegistration(codexScopedPaths(paths), packageRoot(), true);
+    const opencodeReg = await readOpenCodeRegistration(paths, packageRoot(), true);
+    const claudeReg = await readClaudeRegistration(paths, packageRoot(), true);
+    const legacyFileExists = (await readText(paths.legacyConfigFile)) !== undefined;
+    const hasLegacyConfig = beforeConfig.source === 'legacy' || legacyFileExists;
+    const hasLegacyCodex = codexReg.legacyRegistered && !codexReg.canonicalRegistered;
+    const hasLegacyOpencode = opencodeReg.legacyRegistered && !opencodeReg.canonicalRegistered;
+    const hasBothCodex = codexReg.bothRegistered;
+    const hasBothOpencode = opencodeReg.bothRegistered;
+    const hasAnyLegacy = hasLegacyConfig || hasLegacyCodex || hasLegacyOpencode || hasBothCodex || hasBothOpencode;
+    if (!hasAnyLegacy && !clean) {
+        io.write('이전 beginner_bridge 상태를 찾지 못했습니다.\n이미 canonical jutell 상태입니다.\n정리하려면 jutell migrate --clean 을 실행하세요 (canonical이 확인된 뒤에만 레거시를 제거합니다).');
+        return { cancelled: false };
+    }
+    if (!clean) {
+        // Safe migration: READ LEGACY, WRITE CANONICAL, keep legacy
+        const lines = ['JuTell 마이그레이션을 준비합니다. (READ LEGACY → WRITE CANONICAL, keep legacy)'];
+        if (hasLegacyConfig) {
+            await ensureBridgeConfig(paths, undefined);
+            const after = await readBridgeConfig(paths);
+            lines.push(`- 설정: .beginner-bridge.json → .jutell.json 생성 (profile: ${after.config.profile}). 이전 파일은 보존했습니다.`);
+        }
+        else {
+            lines.push('- 설정: .jutell.json 이미 존재 — 유지했습니다.');
+        }
+        // Codex legacy → canonical
+        if (hasLegacyCodex) {
+            await registerMcp(codexScopedPaths(paths), packageRoot(), true);
+            lines.push('- Codex: 이전 beginner_bridge 항목을 보존하고 새 jutell 항목을 추가했습니다. (이전 항목 자동 삭제 안 함)');
+        }
+        else if (hasBothCodex) {
+            lines.push('- Codex: canonical jutell과 legacy beginner_bridge가 모두 있어 그대로 두었습니다.');
+        }
+        else if (codexReg.canonicalRegistered) {
+            lines.push('- Codex: 이미 canonical jutell — 유지했습니다.');
+        }
+        else {
+            lines.push('- Codex: legacy 없음 — 건너뛰었습니다.');
+        }
+        // OpenCode legacy → canonical
+        if (hasLegacyOpencode) {
+            await registerOpenCodeMcp(paths, packageRoot(), true);
+            lines.push('- OpenCode: 이전 beginner_bridge를 보존하고 새 jutell을 추가했습니다.');
+        }
+        else if (hasBothOpencode) {
+            lines.push('- OpenCode: canonical+legacy 모두 있어 그대로 두었습니다.');
+        }
+        else if (opencodeReg.canonicalRegistered) {
+            lines.push('- OpenCode: 이미 canonical jutell — 유지했습니다.');
+        }
+        else {
+            lines.push('- OpenCode: legacy 없음 — 건너뛰었습니다.');
+        }
+        if (claudeReg.registered)
+            lines.push('- Claude Code: 이미 canonical jutell — 유지했습니다.');
+        else
+            lines.push('- Claude Code: legacy 없음 (Claude는 신규 adapter, legacy 없음) — 건너뛰었습니다.');
+        lines.push('레거시는 그대로 보존했습니다.');
+        lines.push('다음: jutell status / jutell doctor 로 확인한 뒤, canonical이 활성화된 것을 확인하면 jutell migrate --clean 으로 레거시를 정리할 수 있습니다.');
+        io.write(lines.join('\n'));
+        return { cancelled: false };
+    }
+    // --clean : remove legacy only after safe verification
+    const errors = [];
+    if (hasLegacyConfig) {
+        // Verify canonical exists and is valid before deleting legacy
+        const canonicalExists = await readText(paths.configFile);
+        if (!canonicalExists)
+            errors.push('.jutell.json이 없어 레거시 .beginner-bridge.json을 삭제하지 않았습니다. 먼저 jutell migrate 를 실행하세요.');
+        else {
+            try {
+                await fs.rm(paths.legacyConfigFile, { force: true });
+                // also legacy local dir if empty? keep for safety, only remove file per spec (not auto delete all data)
+            }
+            catch (e) {
+                errors.push(`레거시 설정 삭제 실패: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+    // Codex legacy clean: only if canonical exists
+    if (hasBothCodex || hasLegacyCodex) {
+        const afterCodex = await readCodexRegistration(codexScopedPaths(paths), packageRoot(), true);
+        if (!afterCodex.canonicalRegistered) {
+            errors.push('Codex에 canonical jutell이 없어 legacy beginner_bridge를 삭제하지 않았습니다.');
+        }
+        else {
+            // Remove only legacy block: read file and strip legacy marker blocks
+            const file = codexScopedPaths(paths).codexConfigFile;
+            const text = (await readText(file)) ?? '';
+            // Use managed.ts patterns: remove only legacy/beginner_bridge blocks, keep canonical and other
+            // Direct patterns for legacy markers (keep canonical JUTELL_CLI_MCP_BEGIN/END)
+            const legacyPattern = /# BEGINNER_BRIDGE_CLI_MCP_BEGIN[\s\S]*?# BEGINNER_BRIDGE_CLI_MCP_END\n?/m;
+            const legacyPattern2 = /# BEGINNER_BRIDGE_MCP_BEGIN[\s\S]*?# BEGINNER_BRIDGE_MCP_END\n?/m;
+            let next = text.replace(legacyPattern, '').replace(legacyPattern2, '');
+            // Also remove unmarked legacy with heuristic: if beginner_bridge still present but not in managed block, check evidence
+            if (/^\s*\[mcp_servers\.beginner_bridge\]/m.test(next) && /(?:assets|apps)[\\/]mcp-server/i.test(next.slice(next.search(/^\s*\[mcp_servers\.beginner_bridge\]/m), next.search(/^\s*\[mcp_servers\.beginner_bridge\]/m) + 1200))) {
+                // Remove that section (from header until next header/marker or end)
+                const idx = next.search(/^\s*\[mcp_servers\.beginner_bridge\]/m);
+                const after = next.slice(idx);
+                const nextHeader = after.slice(1).search(/^\s*\[mcp_servers\./m);
+                const nextMarker = after.search(/#\s*JUTELL_CLI_MCP_BEGIN/m);
+                let cut = after.length;
+                if (nextHeader >= 0)
+                    cut = Math.min(cut, nextHeader + 1);
+                if (nextMarker >= 0)
+                    cut = Math.min(cut, nextMarker);
+                next = next.slice(0, idx) + after.slice(cut);
+            }
+            next = next.replace(/\n{3,}/g, '\n\n').trim();
+            await writeTextSafely(file, next ? `${next}\n` : '');
+        }
+    }
+    // OpenCode legacy clean
+    if (hasBothOpencode || hasLegacyOpencode) {
+        const afterOpencode = await readOpenCodeRegistration(paths, packageRoot(), true);
+        if (!afterOpencode.canonicalRegistered) {
+            errors.push('OpenCode에 canonical jutell이 없어 legacy를 삭제하지 않았습니다.');
+        }
+        else {
+            // For OpenCode, bothRegistered case: remove legacy key from mcp object
+            const { file, text } = await (async () => {
+                const { promises: fs2 } = await import('node:fs');
+                const p = paths.opencodeConfigFile;
+                // opencode may be .jsonc, resolve via readOpenCodeRegistration file
+                const reg = await readOpenCodeRegistration(paths, packageRoot(), true);
+                const t = (await readText(reg.file)) ?? '';
+                return { file: reg.file, text: t };
+            })();
+            try {
+                const parsed = JSON.parse(text.replace(/\/\/.*$/gm, '').replace(/,\s*([}\]])/g, '$1'));
+                if (parsed.mcp && parsed.mcp.beginner_bridge) {
+                    delete parsed.mcp.beginner_bridge;
+                    // Keep jutell, remove managed marker will be regenerated on next write? For clean, just remove legacy key and write plain json
+                    await writeTextSafely(file, `${JSON.stringify(parsed, null, 2)}\n`);
+                }
+            }
+            catch {
+                errors.push('OpenCode 설정 파싱 실패로 legacy 정리를 건너뛰었습니다.');
+            }
+        }
+    }
+    if (errors.length) {
+        io.write(['정리 중 일부를 건너뛰었습니다:', ...errors.map(e => `- ${e}`), '남은 레거시는 jutell doctor 로 확인하세요.'].join('\n'));
+    }
+    else {
+        io.write('레거시 정리가 끝났습니다.\n- .beginner-bridge.json (있었다면) 제거\n- Codex/OpenCode의 beginner_bridge 항목 제거\n관련 없는 설정은 보존했습니다.\njutell status / jutell doctor 로 확인하세요.');
+    }
+    return { cancelled: false };
+}