jutell 0.3.0

package/dist/commands/use.js

@@ -0,0 +1,180 @@
+import { assets, codexScopedPaths, packageRoot } from '../config/paths.js';
+import { readCodexRegistration, registerMcp, snapshot, restore } from '../config/managed.js';
+import { ensureBridgeConfig, setMcpEnabled } from '../installer/config.js';
+import { installSkill, recordSkillFiles, removeAddedSkillFiles } from '../installer/skill.js';
+import { agentsFile, ensureJuTellAgentsBlock } from '../installer/agents.js';
+import { opencodeDetected, readOpenCodeRegistration, registerOpenCodeMcp, setOpenCodeEnabled } from '../installer/opencode.js';
+import { readClaudeRegistration, registerClaudeMcp, removeClaudeMcp } from '../installer/claude.js';
+import { findProvider, supportedProviderNames } from '../installer/providers.js';
+import { claudeDetected, codexDetected } from '../process/system.js';
+function adapterFor(id) {
+    if (id === 'codex') {
+        // Codex only reads MCP servers from its global config (see
+        // codexScopedPaths), regardless of --project/--global.
+        return {
+            detected: codexDetected,
+            read: (paths, enabled) => readCodexRegistration(codexScopedPaths(paths), packageRoot(), enabled),
+            register: (paths, enabled) => registerMcp(codexScopedPaths(paths), packageRoot(), enabled),
+            deactivate: (paths) => registerMcp(codexScopedPaths(paths), packageRoot(), false),
+            notConnectedMessage: '연결된 Codex JuTell MCP가 없습니다. 먼저 jutell use codex 를 실행하세요.',
+        };
+    }
+    if (id === 'claude-code') {
+        // Claude's own scope (local/user) already follows paths.scope directly -
+        // no forced-scope helper needed, unlike Codex.
+        return {
+            detected: claudeDetected,
+            read: (paths, enabled) => readClaudeRegistration(paths, packageRoot(), enabled),
+            register: (paths, enabled) => registerClaudeMcp(paths, packageRoot(), enabled),
+            deactivate: (paths) => removeClaudeMcp(paths, packageRoot()),
+            notConnectedMessage: '연결된 Claude Code JuTell MCP가 없습니다. 먼저 jutell use claude 를 실행하세요.',
+        };
+    }
+    return {
+        detected: opencodeDetected,
+        read: (paths, enabled) => readOpenCodeRegistration(paths, packageRoot(), enabled),
+        register: (paths, enabled) => registerOpenCodeMcp(paths, packageRoot(), enabled),
+        deactivate: (paths) => setOpenCodeEnabled(paths, packageRoot(), false),
+        notConnectedMessage: '연결된 OpenCode JuTell MCP가 없습니다. 먼저 jutell use opencode 를 실행하세요.',
+    };
+}
+async function resolveTarget(args, io) {
+    const target = args[1];
+    if (!target)
+        throw new Error('Agent 이름이 필요합니다. 예: jutell use opencode');
+    const provider = findProvider(target);
+    if (!provider)
+        throw new Error(`알 수 없는 Agent입니다: ${target}\n현재 사용할 수 있는 Agent는 ${supportedProviderNames()}입니다.`);
+    if (provider.status === 'planned') {
+        io.write(`${provider.label} 연결은 아직 준비 중입니다.\n현재 사용할 수 있는 Agent는 ${supportedProviderNames()}입니다.`);
+        return undefined;
+    }
+    return provider;
+}
+async function registrationSnapshots(paths) {
+    const opencode = await readOpenCodeRegistration(paths, packageRoot(), false);
+    const files = [paths.configFile, paths.codexConfigFile, codexScopedPaths(paths).codexConfigFile, opencode.file, paths.claudeConfigFile];
+    if (paths.scope === 'project')
+        files.push(agentsFile(paths.targetRoot));
+    return Promise.all(files.map((file) => snapshot(file)));
+}
+async function registerProviderEnabled(paths, provider, io) {
+    const adapter = adapterFor(provider.id);
+    await adapter.register(paths, true);
+    const current = await adapter.read(paths, true);
+    if (current.canonicalRegistered && current.legacyRegistered) {
+        io.write('\n이전 beginner_bridge 항목을 그대로 두고 새 jutell 항목을 추가했습니다.\n이전 항목은 자동으로 삭제하지 않습니다. 제거는 추후 안전한 마이그레이션에서 안내합니다.');
+    }
+    if (provider.id === 'codex') {
+        io.write('\nCodex는 MCP 서버 목록을 사용자 전역 설정에서만 읽습니다.\nJuTell 프로젝트 규칙(AGENTS.md, Skill, 설정)은 이 프로젝트에 그대로 두고,\nCodex MCP 연결만 사용자 전역 설정(Codex 홈)에 등록했습니다.');
+    }
+}
+async function verifyRegistration(paths, provider) {
+    const current = await adapterFor(provider.id).read(paths, true);
+    if (!current.canonicalRegistered || !current.enabled)
+        throw new Error(`${provider.label} 연결 설정을 검증하지 못했습니다. jutell doctor를 실행해 주세요.`);
+}
+function printSuccess(io, provider, extra) {
+    io.write(`${provider.label} 연결이 끝났습니다.\n\n이제 ${provider.label}에서 새 대화를 열면\nJuTell이 자동으로 적용됩니다.\n실제 적용 여부는 새 대화에서 확인할 수 있습니다.\n\n연결 확인\n- AI 연결 설정\n- JuTell 규칙 연결\n- 기존 ${provider.label} 설정 보존`);
+    if (extra.othersDisabled)
+        io.write('\n\n다른 Agent의 JuTell 연결은 비활성화했습니다.');
+    if (extra.keepNote)
+        io.write('\n기존 다른 Agent 연결은 유지했습니다.');
+    if (!extra.detected)
+        io.write(`\n참고: ${provider.label} 명령을 찾지 못했습니다. 설치 후 다시 실행하세요.`);
+}
+async function rollback(snapshots, changed, paths) {
+    for (const item of snapshots)
+        await restore(item);
+    await removeAddedSkillFiles(paths.skillRoot, changed);
+}
+export async function useCommand(paths, options, io, args) {
+    const provider = await resolveTarget(args, io);
+    if (!provider)
+        return { cancelled: true };
+    const detected = adapterFor(provider.id).detected();
+    const snapshots = await registrationSnapshots(paths);
+    let changed = [];
+    try {
+        await ensureBridgeConfig(paths, options.profile);
+        const skillResult = await installSkill(assets().skill, paths.skillRoot);
+        changed = skillResult.changed;
+        if (paths.scope === 'project')
+            await ensureJuTellAgentsBlock(paths.targetRoot);
+        await setMcpEnabled(paths, true);
+        await registerProviderEnabled(paths, provider, io);
+        await recordSkillFiles(paths, changed);
+        await verifyRegistration(paths, provider);
+        printSuccess(io, provider, { detected, skill: true, agents: paths.scope === 'project', keepNote: true });
+        return { cancelled: false };
+    }
+    catch (error) {
+        await rollback(snapshots, changed, paths);
+        throw error;
+    }
+}
+export async function connectCommand(paths, options, io, args) {
+    const provider = await resolveTarget(args, io);
+    if (!provider)
+        return { cancelled: true };
+    const detected = adapterFor(provider.id).detected();
+    const snapshots = await registrationSnapshots(paths);
+    try {
+        await ensureBridgeConfig(paths, undefined);
+        await setMcpEnabled(paths, true);
+        await registerProviderEnabled(paths, provider, io);
+        await verifyRegistration(paths, provider);
+        printSuccess(io, provider, { detected, keepNote: true });
+        return { cancelled: false };
+    }
+    catch (error) {
+        await rollback(snapshots, [], paths);
+        throw error;
+    }
+}
+export async function disconnectCommand(paths, options, io, args) {
+    const provider = await resolveTarget(args, io);
+    if (!provider)
+        return { cancelled: true };
+    const adapter = adapterFor(provider.id);
+    const current = await adapter.read(paths, false);
+    if (current.conflict)
+        throw new Error(`${provider.label} 설정에 같은 이름의 관리되지 않는 MCP 항목이 있어 자동 변경하지 않았습니다.`);
+    if (!current.registered) {
+        io.write(adapter.notConnectedMessage);
+        return { cancelled: false };
+    }
+    await adapter.deactivate(paths);
+    io.write(`${provider.label} 연결을 끊었습니다.\nJuTell MCP는 비활성화했고 설정 항목은 유지됩니다. 새 ${provider.label} 세션부터 사용되지 않습니다.`);
+    return { cancelled: false };
+}
+export async function switchCommand(paths, options, io, args) {
+    const provider = await resolveTarget(args, io);
+    if (!provider)
+        return { cancelled: true };
+    const detected = adapterFor(provider.id).detected();
+    const snapshots = await registrationSnapshots(paths);
+    try {
+        for (const other of ['codex', 'opencode', 'claude-code']) {
+            if (other === provider.id)
+                continue;
+            const otherAdapter = adapterFor(other);
+            const current = await otherAdapter.read(paths, false);
+            const otherLabel = findProvider(other)?.label ?? other;
+            if (current.conflict)
+                throw new Error(`${otherLabel} 설정에 같은 이름의 관리되지 않는 MCP 항목이 있어 자동 변경하지 않았습니다.`);
+            if (current.registered && current.enabled)
+                await otherAdapter.deactivate(paths);
+        }
+        await ensureBridgeConfig(paths, undefined);
+        await setMcpEnabled(paths, true);
+        await registerProviderEnabled(paths, provider, io);
+        await verifyRegistration(paths, provider);
+        printSuccess(io, provider, { detected, othersDisabled: true });
+        return { cancelled: false };
+    }
+    catch (error) {
+        await rollback(snapshots, [], paths);
+        throw error;
+    }
+}

package/dist/compat.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { run } from './cli.js';
+import { createIo } from './output/format.js';
+const code = await run(process.argv.slice(2), createIo(), true);
+process.exitCode = code;

package/dist/config/managed.js

@@ -0,0 +1,257 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { assets } from './paths.js';
+export const BEGIN_MARKER = '# JUTELL_CLI_MCP_BEGIN';
+export const END_MARKER = '# JUTELL_CLI_MCP_END';
+const PREVIOUS_BEGIN_MARKER = '# BEGINNER_BRIDGE_CLI_MCP_BEGIN';
+const PREVIOUS_END_MARKER = '# BEGINNER_BRIDGE_CLI_MCP_END';
+const LEGACY_BEGIN_MARKER = '# BEGINNER_BRIDGE_MCP_BEGIN';
+const LEGACY_END_MARKER = '# BEGINNER_BRIDGE_MCP_END';
+const CANONICAL_MCP_KEY = 'jutell';
+const LEGACY_MCP_KEY = 'beginner_bridge';
+export const FEATURE_IDS = ['changeSummary', 'userVisibleChanges', 'internalChanges', 'mainFiles', 'explainedDiff', 'glossary', 'validationResults', 'riskAssessment', 'userActions', 'nextActionSuggestions', 'requestClarificationGuide', 'manualEditGuidance', 'requestBuilder'];
+export const PROFILES = ['minimal', 'balanced', 'learning', 'detailed'];
+export const PROFILE_FEATURES = {
+    minimal: { changeSummary: true, userVisibleChanges: true, internalChanges: false, mainFiles: false, explainedDiff: false, glossary: false, validationResults: true, riskAssessment: false, userActions: true, nextActionSuggestions: false, requestClarificationGuide: false, manualEditGuidance: false, requestBuilder: true },
+    balanced: { changeSummary: true, userVisibleChanges: true, internalChanges: true, mainFiles: true, explainedDiff: true, glossary: true, validationResults: true, riskAssessment: true, userActions: true, nextActionSuggestions: true, requestClarificationGuide: true, manualEditGuidance: true, requestBuilder: true },
+    learning: { changeSummary: true, userVisibleChanges: true, internalChanges: true, mainFiles: true, explainedDiff: true, glossary: true, validationResults: true, riskAssessment: true, userActions: true, nextActionSuggestions: true, requestClarificationGuide: true, manualEditGuidance: true, requestBuilder: true },
+    detailed: { changeSummary: true, userVisibleChanges: true, internalChanges: true, mainFiles: true, explainedDiff: true, glossary: true, validationResults: true, riskAssessment: true, userActions: true, nextActionSuggestions: true, requestClarificationGuide: true, manualEditGuidance: true, requestBuilder: true },
+};
+const fallbackConfig = {
+    version: 1,
+    profile: 'balanced',
+    features: { ...PROFILE_FEATURES.balanced },
+    limits: { maxMainFiles: 5, maxGlossaryTerms: 3, compactReportMaxSentences: 12 },
+    mcp: { enabled: false },
+    usageMeasurement: { localCountersEnabled: false },
+};
+export async function exists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readText(file) {
+    try {
+        return await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function snapshot(file) {
+    const content = await readText(file);
+    return content === undefined ? { file, existed: false } : { file, existed: true, content };
+}
+export async function restore(snapshotValue) {
+    if (snapshotValue.existed) {
+        await fs.mkdir(path.dirname(snapshotValue.file), { recursive: true });
+        await fs.writeFile(snapshotValue.file, snapshotValue.content ?? '', 'utf8');
+    }
+    else {
+        await fs.rm(snapshotValue.file, { force: true });
+    }
+}
+export async function writeTextSafely(file, content) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.beginner-bridge-tmp-${process.pid}`;
+    await fs.writeFile(temporary, content, 'utf8');
+    try {
+        await fs.rename(temporary, file);
+    }
+    catch (error) {
+        await fs.rm(temporary, { force: true });
+        throw error;
+    }
+}
+export async function backupFile(file) {
+    if (await exists(file))
+        await fs.copyFile(file, `${file}.previous`);
+}
+async function defaultConfig() {
+    const content = await readText(assets().defaultConfig);
+    if (!content)
+        return structuredClone(fallbackConfig);
+    try {
+        return normalizeConfig(JSON.parse(content));
+    }
+    catch {
+        return structuredClone(fallbackConfig);
+    }
+}
+export function normalizeConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return structuredClone(fallbackConfig);
+    const input = value;
+    const profile = typeof input.profile === 'string' && PROFILES.includes(input.profile) ? input.profile : 'balanced';
+    const inputFeatures = input.features && typeof input.features === 'object' && !Array.isArray(input.features) ? input.features : {};
+    const features = Object.fromEntries(FEATURE_IDS.map((id) => [id, typeof inputFeatures[id] === 'boolean' ? inputFeatures[id] : PROFILE_FEATURES[profile][id]]));
+    const inputLimits = input.limits && typeof input.limits === 'object' && !Array.isArray(input.limits) ? input.limits : {};
+    const numberOr = (key, fallback) => typeof inputLimits[key] === 'number' && Number.isInteger(inputLimits[key]) ? inputLimits[key] : fallback;
+    const inputMcp = input.mcp && typeof input.mcp === 'object' && !Array.isArray(input.mcp) ? input.mcp : {};
+    const inputUsageMeasurement = input.usageMeasurement && typeof input.usageMeasurement === 'object' && !Array.isArray(input.usageMeasurement) ? input.usageMeasurement : {};
+    const inputVoice = input.voice && typeof input.voice === 'object' && !Array.isArray(input.voice) ? input.voice : {};
+    return {
+        version: 1,
+        profile,
+        features,
+        limits: { maxMainFiles: numberOr('maxMainFiles', 5), maxGlossaryTerms: numberOr('maxGlossaryTerms', 3), compactReportMaxSentences: numberOr('compactReportMaxSentences', 12) },
+        mcp: { enabled: inputMcp.enabled === true },
+        usageMeasurement: { localCountersEnabled: inputUsageMeasurement.localCountersEnabled === true },
+        ...(typeof inputVoice.preset === 'string' ? { voice: { preset: inputVoice.preset } } : {}),
+    };
+}
+export async function readBridgeConfig(paths) {
+    const preferred = await readText(paths.configFile);
+    const raw = preferred ?? await readText(paths.legacyConfigFile);
+    const source = preferred !== undefined ? 'new' : raw !== undefined ? 'legacy' : 'default';
+    if (!raw)
+        return { config: await defaultConfig(), exists: false, valid: true, source };
+    try {
+        const parsed = JSON.parse(raw);
+        const valid = parsed.version === 1 && typeof parsed.profile === 'string' && PROFILES.includes(parsed.profile);
+        return { config: normalizeConfig(parsed), exists: true, valid, source };
+    }
+    catch {
+        return { config: await defaultConfig(), exists: true, valid: false, source };
+    }
+}
+export async function writeBridgeConfig(paths, config) {
+    await writeTextSafely(paths.configFile, `${JSON.stringify(config, null, 2)}\n`);
+}
+function markerPair(begin, end) {
+    return new RegExp(`${begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+}
+function managedPatterns() {
+    return [
+        markerPair(BEGIN_MARKER, END_MARKER),
+        markerPair(PREVIOUS_BEGIN_MARKER, PREVIOUS_END_MARKER),
+        markerPair(LEGACY_BEGIN_MARKER, LEGACY_END_MARKER),
+    ];
+}
+function managedBlocks(content) {
+    return managedPatterns().flatMap((pattern) => content.match(pattern)?.[0] ?? []);
+}
+function withoutManagedBlocks(content) {
+    return managedPatterns().reduce((text, pattern) => text.replace(pattern, ''), content);
+}
+function withoutCanonicalBlock(content) {
+    return content.replace(markerPair(BEGIN_MARKER, END_MARKER), '');
+}
+function hasMcpKey(content, key) {
+    return new RegExp(`^\\s*\\[mcp_servers\\.${key}\\]\\s*$`, 'm').test(content);
+}
+function hasJuTellMcpEvidence(content, key) {
+    const keyPattern = new RegExp(`^\\s*\\[mcp_servers\\.${key}\\]\\s*$`, 'm');
+    const match = content.match(keyPattern);
+    if (!match || match.index === undefined)
+        return false;
+    const slice = content.slice(match.index, match.index + 1200);
+    // JuTell's server always contains `assets/mcp-server` or `apps/mcp-server` in args (see buildMcpBlock)
+    // Unrelated custom entries (e.g. jira, other, even a custom `jutell` pointing to `not-mcp-server.js`) do not –
+    // this prevents broadly adopting arbitrary unmarked MCP entries.
+    return /(?:assets|apps)[\\/]mcp-server/i.test(slice);
+}
+function tomlString(value) {
+    return JSON.stringify(value.replaceAll('\\', '/'));
+}
+export function buildMcpBlock(scope, packageRoot, enabled) {
+    const serverEntry = path.join(packageRoot, 'assets', 'mcp-server', 'index.js');
+    const lines = [BEGIN_MARKER, `[mcp_servers.${CANONICAL_MCP_KEY}]`, `command = ${tomlString(process.execPath)}`, `args = [${tomlString(serverEntry)}]`];
+    if (scope.scope === 'project')
+        lines.push('cwd = "."');
+    lines.push(`enabled = ${enabled ? 'true' : 'false'}`, 'required = false', 'default_tools_approval_mode = "prompt"', END_MARKER);
+    return lines.join('\n');
+}
+export async function readCodexRegistration(paths, packageRoot, enabled) {
+    const content = await readText(paths.codexConfigFile) ?? '';
+    const blocks = managedBlocks(content);
+    const canonicalManaged = blocks.find((block) => hasMcpKey(block, CANONICAL_MCP_KEY));
+    const legacyManaged = blocks.find((block) => hasMcpKey(block, LEGACY_MCP_KEY));
+    const canonicalRegistered = hasMcpKey(content, CANONICAL_MCP_KEY);
+    const legacyRegistered = hasMcpKey(content, LEGACY_MCP_KEY);
+    const canonicalHeuristic = !canonicalManaged && canonicalRegistered && hasJuTellMcpEvidence(content, CANONICAL_MCP_KEY);
+    const legacyHeuristic = !legacyManaged && legacyRegistered && hasJuTellMcpEvidence(content, LEGACY_MCP_KEY);
+    const registered = Boolean(canonicalManaged || legacyManaged || canonicalHeuristic || legacyHeuristic);
+    const conflict = !registered && (canonicalRegistered || legacyRegistered);
+    const enabledFlag = (() => {
+        if (canonicalManaged)
+            return /^\s*enabled\s*=\s*true\s*$/m.test(canonicalManaged);
+        if (canonicalHeuristic) {
+            const keyPattern = new RegExp(`^\\s*\\[mcp_servers\\.${CANONICAL_MCP_KEY}\\]\\s*$`, 'm');
+            const m = content.match(keyPattern);
+            if (m && m.index !== undefined) {
+                const slice = content.slice(m.index, m.index + 1200);
+                return /^\s*enabled\s*=\s*true\s*$/m.test(slice);
+            }
+        }
+        if (legacyManaged)
+            return false;
+        if (legacyHeuristic) {
+            const keyPattern = new RegExp(`^\\s*\\[mcp_servers\\.${LEGACY_MCP_KEY}\\]\\s*$`, 'm');
+            const m = content.match(keyPattern);
+            if (m && m.index !== undefined) {
+                const slice = content.slice(m.index, m.index + 1200);
+                // legacy-only state is treated as registered but not enabled for canonical;
+                // status warning will guide to `jutell use codex` to add canonical.
+                return false;
+            }
+        }
+        return false;
+    })();
+    return {
+        content,
+        exists: content.length > 0,
+        registered,
+        conflict,
+        enabled: enabledFlag,
+        canonicalRegistered,
+        legacyRegistered,
+        bothRegistered: canonicalRegistered && legacyRegistered,
+        preview: buildMcpBlock(paths, packageRoot, enabled),
+    };
+}
+export async function registerMcp(paths, packageRoot, enabled) {
+    const current = await readCodexRegistration(paths, packageRoot, enabled);
+    if (current.conflict)
+        throw new Error('Codex 설정에 같은 이름의 관리되지 않는 MCP 항목이 있어 자동 변경하지 않았습니다.');
+    if (current.canonicalRegistered && current.enabled === enabled)
+        return current;
+    await backupFile(paths.codexConfigFile);
+    const withoutManaged = withoutCanonicalBlock(current.content).replace(/\n{3,}/g, '\n\n').trimEnd();
+    const next = `${withoutManaged}${withoutManaged ? '\n\n' : ''}${current.preview}\n`;
+    await writeTextSafely(paths.codexConfigFile, next);
+    return readCodexRegistration(paths, packageRoot, enabled);
+}
+export async function removeMcp(paths, packageRoot) {
+    const current = await readCodexRegistration(paths, packageRoot, false);
+    if (current.conflict)
+        throw new Error('관리되지 않는 같은 이름의 MCP 항목은 자동으로 제거하지 않습니다.');
+    if (!current.registered)
+        return current;
+    await backupFile(paths.codexConfigFile);
+    const next = withoutManagedBlocks(current.content).replace(/\n{3,}/g, '\n\n').trim();
+    await writeTextSafely(paths.codexConfigFile, next ? `${next}\n` : '');
+    return readCodexRegistration(paths, packageRoot, false);
+}
+export async function readVersionInfo() {
+    const content = await readText(assets().version);
+    const fallback = { cli: '0.2.1', skill: '확인 필요', mcp: '0.1.0', admin: '0.1.0' };
+    if (!content)
+        return fallback;
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function parseSkillVersion(skillText) {
+    if (!skillText)
+        return undefined;
+    const match = skillText.match(/jutellSkillVersion\s*:\s*["']?([0-9A-Za-z.\-]+)/);
+    return match ? match[1] : undefined;
+}

package/dist/config/paths.js

@@ -0,0 +1,100 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+export function assets() {
+    const root = path.join(packageRoot(), 'assets');
+    return {
+        root,
+        skill: path.join(root, 'skill'),
+        mcpServer: path.join(root, 'mcp-server'),
+        localAdmin: path.join(root, 'local-admin'),
+        localAdminServer: path.join(root, 'local-admin-server.js'),
+        defaultConfig: path.join(root, 'default-config.json'),
+        version: path.join(root, 'version.json'),
+    };
+}
+export function codexHome() {
+    const override = process.env.CODEX_HOME;
+    return path.resolve(override && override.trim() ? override : path.join(userHome(), '.codex'));
+}
+export function opencodeConfigDir() {
+    return path.join(userHome(), '.config', 'opencode');
+}
+/**
+ * Real Claude Code CLI reads its own profile (settings, credentials, and
+ * `.claude.json`) from `$CLAUDE_CONFIG_DIR` when set, otherwise the user's
+ * home directory directly (verified: `.claude.json` sits at
+ * `<CLAUDE_CONFIG_DIR>/.claude.json`, not inside a `.claude/` subfolder).
+ * `userHome()` is used as the fallback base (not raw `os.homedir()`) purely
+ * so JuTell's own JUTELL_HOME/BEGINNER_BRIDGE_HOME test-isolation override
+ * also isolates Claude by default; every subprocess call this CLI makes to
+ * the real `claude` binary explicitly passes CLAUDE_CONFIG_DIR set to this
+ * same value, so the two can never disagree about which file is meant.
+ */
+export function claudeHome() {
+    const override = process.env.CLAUDE_CONFIG_DIR;
+    return path.resolve(override && override.trim() ? override : userHome());
+}
+export function userHome() {
+    const override = process.env.JUTELL_HOME ?? process.env.BEGINNER_BRIDGE_HOME;
+    return path.resolve(override && override.trim() ? override : os.homedir());
+}
+export function resolveScope(scope, cwd = process.cwd()) {
+    if (scope === 'global') {
+        const home = userHome();
+        return {
+            scope,
+            targetRoot: home,
+            skillRoot: path.join(home, '.agents', 'skills', 'beginner-bridge'),
+            configFile: path.join(home, '.jutell.json'),
+            legacyConfigFile: path.join(home, '.beginner-bridge.json'),
+            codexConfigFile: path.join(codexHome(), 'config.toml'),
+            opencodeConfigFile: path.join(opencodeConfigDir(), 'opencode.json'),
+            claudeConfigFile: path.join(claudeHome(), '.claude.json'),
+            dataRoot: path.join(home, '.jutell-local'),
+            legacyDataRoot: path.join(home, '.beginner-bridge-local'),
+        };
+    }
+    const projectRoot = path.resolve(cwd);
+    return {
+        scope,
+        targetRoot: projectRoot,
+        skillRoot: path.join(projectRoot, '.agents', 'skills', 'beginner-bridge'),
+        configFile: path.join(projectRoot, '.jutell.json'),
+        legacyConfigFile: path.join(projectRoot, '.beginner-bridge.json'),
+        codexConfigFile: path.join(projectRoot, '.codex', 'config.toml'),
+        opencodeConfigFile: path.join(projectRoot, 'opencode.json'),
+        // Claude's own file location never varies by JuTell's scope choice -
+        // only *which key inside it* (top-level `mcpServers` for global/user,
+        // `projects[targetRoot].mcpServers` for project/local) does. See
+        // installer/claude.ts.
+        claudeConfigFile: path.join(claudeHome(), '.claude.json'),
+        dataRoot: path.join(projectRoot, '.jutell-local'),
+        legacyDataRoot: path.join(projectRoot, '.beginner-bridge-local'),
+    };
+}
+export function safeLocation(scope, kind) {
+    if (kind === 'codex')
+        return '사용자 Codex 설정 (전역)';
+    if (scope === 'global')
+        return '사용자 전역 설정';
+    return '현재 프로젝트/.jutell.json';
+}
+/**
+ * Real Codex CLI only reads MCP server definitions from its global
+ * `$CODEX_HOME/config.toml` — it never consumes a project-scoped
+ * `<project>/.codex/config.toml` (verified empirically: `codex mcp list`
+ * returns no servers when only a project-scope file exists). So any
+ * ScopePaths used to read/write/remove a Codex MCP registration must
+ * always target the real global file, regardless of the invocation's
+ * `--project`/`--global` scope — otherwise JuTell would report success
+ * while Codex never actually sees the server. `.jutell.json`, the Skill,
+ * and the AGENTS.md block are unaffected and keep following the
+ * requested scope; only the Codex MCP file location is forced.
+ */
+export function codexScopedPaths(paths) {
+    return { ...paths, scope: 'global', codexConfigFile: path.join(codexHome(), 'config.toml') };
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './cli.js';
+const code = await run(process.argv.slice(2));
+process.exitCode = code;

package/dist/installer/agents.js

@@ -0,0 +1,42 @@
+import { readText, writeTextSafely } from '../config/managed.js';
+import path from 'node:path';
+export const JUTELL_AGENTS_BEGIN = '<!-- BEGIN JUTELL MANAGED BLOCK -->';
+export const JUTELL_AGENTS_END = '<!-- END JUTELL MANAGED BLOCK -->';
+const managedBlock = `${JUTELL_AGENTS_BEGIN}
+## JuTell
+
+- 코드 또는 문서 변경 후 \`.agents/skills/beginner-bridge/SKILL.md\`와 \`.jutell.json\`을 먼저 읽습니다. 소유자 대상 구현/보고 전에는 JuTell 보고 규칙을 먼저 적용해 최종 답변을 작성합니다.
+- JuTell MCP가 보이면 canonical \`jutell\` 서버를 사용합니다. \`jutell\`과 legacy \`beginner_bridge\`가 모두 보이면 \`jutell\`을 우선하고 \`beginner_bridge\`는 호환용으로만 사용합니다.
+- 확인하지 않은 결과를 사실처럼 표현하지 않습니다.
+- 비밀정보를 명령 출력이나 보고서에 포함하지 않습니다.
+- 외부 전송 없이 현재 프로젝트의 로컬 설정을 기준으로 작업합니다.
+${JUTELL_AGENTS_END}`;
+function markerPattern() {
+    return new RegExp(`${JUTELL_AGENTS_BEGIN}[\\s\\S]*?${JUTELL_AGENTS_END}`, 'm');
+}
+export function agentsFile(projectRoot) {
+    return path.join(projectRoot, 'AGENTS.md');
+}
+export async function hasJuTellAgentsBlock(projectRoot) {
+    const content = await readText(agentsFile(projectRoot));
+    return Boolean(content && markerPattern().test(content));
+}
+export async function ensureJuTellAgentsBlock(projectRoot) {
+    const file = agentsFile(projectRoot);
+    const current = await readText(file) ?? '';
+    const next = markerPattern().test(current)
+        ? current.replace(markerPattern(), managedBlock).replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
+        : `${current.trimEnd()}${current.trimEnd() ? '\n\n' : ''}${managedBlock}\n`;
+    if (next !== current)
+        await writeTextSafely(file, next);
+    return { changed: next !== current };
+}
+export async function removeJuTellAgentsBlock(projectRoot) {
+    const file = agentsFile(projectRoot);
+    const current = await readText(file);
+    if (!current || !markerPattern().test(current))
+        return { changed: false };
+    const next = current.replace(markerPattern(), '').replace(/\n{3,}/g, '\n\n').trimEnd();
+    await writeTextSafely(file, next ? `${next}\n` : '');
+    return { changed: true };
+}