@decencia/ch-cli 1.34.5 → 1.35.0

package/dist/commands/skills.js

@@ -50,12 +50,20 @@ exports.prepareSkillUpload = prepareSkillUpload;
 exports.filterSkillsByGroup = filterSkillsByGroup;
 exports.collectTag = collectTag;
 exports.filterSkillsByTag = filterSkillsByTag;
+exports.planConfirmation = planConfirmation;
+exports.isAffirmative = isAffirmative;
 exports.registerSkillsCommand = registerSkillsCommand;
+exports.parseSyncScopes = parseSyncScopes;
+const chalk_1 = __importDefault(require("chalk"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
 const js_yaml_1 = require("js-yaml");
 const form_data_1 = __importDefault(require("form-data"));
 const client_1 = require("../client");
+const config_1 = require("../config");
+const skills_cache_1 = require("../skills-cache");
+const skills_diff_1 = require("../skills-diff");
 const output_1 = require("../output");
 /** 스킬 폴더 규약상 고정된 매니페스트 파일명. frontmatter 의 출처. */
 exports.SKILL_MANIFEST_FILENAME = 'SKILL.md';
@@ -267,6 +275,47 @@ function filterSkillsByTag(rows, tag) {
         return rows;
     return rows.filter((r) => (r.tags ?? []).includes(target));
 }
+/**
+ * 확인을 어떻게 받을지 정한다(순수 판정 — 실제 입출력은 호출측).
+ *
+ * `--yes` 가 없는데 stdin 이 대화형이 아니면(파이프·CI·`--json` 기계 모드) 물어볼
+ * 방법이 없다. 이때 조용히 삭제하면 위험하고, 조용히 성공한 척 끝내면 호출한
+ * 스크립트가 삭제된 줄 안다. 그래서 refuse — 실행하지 않고 exit≠0 으로 알린다.
+ */
+function planConfirmation(opts) {
+    if (opts.yes)
+        return 'proceed';
+    return opts.interactive ? 'prompt' : 'refuse';
+}
+/**
+ * 확인 프롬프트 응답을 해석한다 — `y`/`yes`(대소문자·공백 무시)만 승인.
+ * 빈 입력(그냥 엔터)을 포함한 그 외 모든 입력은 거부다(파괴적 작업의 안전 기본값).
+ */
+function isAffirmative(answer) {
+    const normalized = (answer ?? '').trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}
+/**
+ * 확인 질문을 stderr 로 묻고 한 줄을 읽는다.
+ * 질문을 stdout 이 아닌 stderr 로 보내는 이유는 stdout 출력 계약(원문/JSON 전용)을
+ * 어떤 모드에서도 깨지 않기 위해서다.
+ */
+async function askConfirmation(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(question, resolve);
+        });
+        return isAffirmative(answer);
+    }
+    finally {
+        rl.close();
+        process.stdin.pause(); // 남은 stdin 이 프로세스를 붙잡지 않도록.
+    }
+}
 /**
  * 폴더구조를 보존한 multipart 폼을 만든다.
  * `files` 를 상대경로 정렬 순서대로 append 하고, 같은 순서의 `paths`(JSON 배열)를
@@ -291,11 +340,136 @@ function buildUploadForm(uploads, group, tags) {
     }
     return form;
 }
+// ── 캐시 적재(use) 보조 ───────────────────────────────────────────────────
+/**
+ * 캐시 적재는 본조회(get/list)와 달리 실패해도 캐시본으로 진행해야 하므로
+ * 에러 인터셉터가 없는 probe 클라이언트를 쓴다(연결 실패에 process.exit 하지
+ * 않는다). 다만 이쪽은 부가 조회가 아니라 본작업이라 타임아웃은 본조회와 맞춘다.
+ */
+const SKILL_FETCH_TIMEOUT_MS = 30000;
+/**
+ * use 의 사람용 메시지는 항상 stderr 로 보낸다.
+ * stdout 은 SKILL.md 본문(기계 모드면 JSON 하나) 전용이라, 기본 모드에서 stdout
+ * 으로 나가는 printInfo/printWarning 을 쓰면 본문이 오염된다.
+ */
+function stderrNote(message, tone = 'info') {
+    console.error(tone === 'warn' ? chalk_1.default.yellow(message) : chalk_1.default.gray(message));
+}
+/** 실패 사유를 한 줄로 요약한다(경고문에 끼워 넣는 용도). */
+function describeRequestFailure(error) {
+    const status = error?.response?.status;
+    if (status) {
+        const data = error?.response?.data;
+        const serverMessage = typeof data === 'object' && data ? data.message || data.error : '';
+        return serverMessage ? `${status} ${serverMessage}` : `${status}`;
+    }
+    if (error?.code)
+        return String(error.code);
+    return error?.message ? String(error.message) : '알 수 없는 오류';
+}
+/** 스코프의 목록(신선도 맵 원본)을 읽는다. 실패는 호출측이 처리한다. */
+async function fetchSkillIndex(client, scope) {
+    const { data } = await client.get(skillBasePath(scope));
+    return Array.isArray(data) ? data : [];
+}
+/** 목록에서 이름으로 항목(문서 id + 신선도 토큰)을 뽑는다. */
+function indexEntryOf(rows, name) {
+    const row = rows.find((r) => r?.name === name);
+    if (!row?.id)
+        return undefined;
+    return { id: String(row.id), token: (0, skills_cache_1.freshnessToken)(row) };
+}
+/**
+ * 스킬 하나를 통째로 받는다 — SKILL.md 본문(단건 응답) + 번들 파일(파일 API).
+ * 번들은 상대경로 그대로 받아 캐시가 폴더 구조를 보존하게 한다.
+ */
+async function downloadSkill(client, scope, entry) {
+    const { data } = await client.get(`${skillBasePath(scope)}/${entry.id}`);
+    const relPaths = (Array.isArray(data?.files) ? data.files : [])
+        .map((f) => String(f?.path ?? ''))
+        .filter((p) => p.length > 0);
+    const manifestPath = pickRootSkillMd(relPaths) ?? exports.SKILL_MANIFEST_FILENAME;
+    const files = [];
+    for (const relPath of relPaths) {
+        // 매니페스트는 단건 응답의 content 가 이미 원문이라 다시 받지 않는다.
+        if (relPath === manifestPath)
+            continue;
+        const res = await client.get(`${skillBasePath(scope)}/${entry.id}/file`, {
+            params: { path: relPath },
+            responseType: 'arraybuffer',
+        });
+        files.push({ path: relPath, data: Buffer.from(res.data) });
+    }
+    return {
+        id: entry.id,
+        // 실제로 받은 문서의 시각이 정본이다 — 목록을 읽은 뒤 서버가 바뀌었을 수 있다.
+        token: (0, skills_cache_1.freshnessToken)(data) ?? entry.token,
+        manifestPath,
+        content: typeof data?.content === 'string' ? data.content : '',
+        files,
+    };
+}
+/**
+ * use 의 출력 — 기본은 본문 원문, 기계 모드면 캐시 위치까지 담은 JSON 하나.
+ *
+ * 캐시 폴더는 어느 경로로 끝나든 stderr 로 알린다. SKILL.md 가 번들 파일
+ * (`references/...`)을 상대경로로 가리키므로, 그 폴더를 모르면 본문만 읽고
+ * 참조를 열 수 없다.
+ */
+function emitSkill(view, globalOpts) {
+    if (view.dir) {
+        const what = view.source === 'cache' ? '캐시본' : '내려받아 캐시했습니다';
+        stderrNote(`스킬 "${view.name}"(${view.scope}) ${what} — 파일 ${view.files.length}개, ${view.dir}`);
+    }
+    if ((0, output_1.isMachineMode)()) {
+        (0, output_1.formatOutput)(view, globalOpts);
+    }
+    else {
+        process.stdout.write(view.content);
+    }
+}
+/**
+ * 사용 기록 ping 의 제한시간. 적재가 끝난 뒤에 나가는 뒷정리라 본조회(30초)보다
+ * 짧게 잡는다 — 서버가 굼뜨다고 다 끝난 명령이 오래 매달려 있으면 안 된다.
+ */
+const SKILL_PING_TIMEOUT_MS = 3000;
+/**
+ * 사용 기록 ping(SKILL-015) — 적재 1회를 서버에 알린다.
+ *
+ * 적재를 블로킹하지 않는다: 본문을 이미 낸 뒤에 보내고, 실패는 삼킨다.
+ * 오프라인이면 조용히 넘어간다 — 기록 하나 놓친 걸로 사람을 경고로 붙잡지 않는다.
+ * 캐시가 최신이라 네트워크가 0회인 적재에서도 보낸다. 그래야 계측이 된다.
+ *
+ * 결과를 무시하면서도 기다리는 이유: 요청이 떠 있는 동안은 노드가 어차피 프로세스를
+ * 붙잡는다. 안 기다리는 척해 봐야 종료가 늦어지는 건 같으니 명시적으로 기다린다.
+ *
+ * 그래서 이 수치는 정확한 계수가 아니라 경향치다. 실패한 ping 은 그냥 누락된다.
+ */
+async function pingSkillUsage(client, scope, id) {
+    try {
+        // 본문은 빈 객체여야 한다. 클라이언트가 Content-Type: application/json 을
+        // 달고 나가는데 null 을 주면 axios 가 "null" 을 실어 보내고, 서버의 JSON
+        // 파서가 strict 모드라 그걸 400 으로 되던진다(기록이 통째로 유실된다).
+        await client.post(`${skillBasePath(scope)}/${id}/use`, {}, { timeout: SKILL_PING_TIMEOUT_MS });
+    }
+    catch {
+        // 기록 실패는 적재의 성패와 무관하다.
+    }
+}
+/** 목록 스냅샷 저장은 부가 효과다 — 실패해도 명령이 흔들리면 안 된다. */
+function saveIndexSnapshotSafely(scope, projectId, rows) {
+    try {
+        (0, skills_cache_1.saveIndexSnapshot)(scope, projectId, rows);
+    }
+    catch {
+        // 캐시 쓰기 실패는 조회 결과에 영향을 주지 않는다.
+    }
+}
 // ── 커맨드 등록 ────────────────────────────────────────────────────────────
 function registerSkillsCommand(program) {
     const skills = program
         .command('skills')
-        .description('스킬 목록·조회·등록·수정 (E19) — ch-api /skills 프록시');
+        .description('스킬 목록·조회·등록·수정·삭제 (E19) — ch-api /skills 프록시');
     // ch skills list
     skills
         .command('list')
@@ -306,6 +480,7 @@ function registerSkillsCommand(program) {
         .action(async (options) => {
         const globalOpts = program.opts();
         const scopes = scopesToList(options);
+        const projectId = (0, config_1.getProjectContext)(globalOpts.project)?.projectId ?? null;
         const client = (0, client_1.createClient)({ projectId: globalOpts.project });
         // 스코프별로 독립 조회해 합친다 — 한쪽(예: 프로젝트 컨텍스트 미해석)이
         // 실패해도 다른 쪽 결과는 보존한다(인터셉터가 exitCode 로 실패를 알린다).
@@ -313,8 +488,13 @@ function registerSkillsCommand(program) {
         for (const scope of scopes) {
             try {
                 const { data } = await client.get(skillBasePath(scope));
-                if (Array.isArray(data))
+                if (Array.isArray(data)) {
                     merged.push(...data);
+                    // 이 응답이 곧 신선도 맵이다(SKILL-011). 저장해 두면 뒤이은
+                    // `ch skills use` 가 서버를 다시 묻지 않는다. 필터(--group/--tag)
+                    // 이전의 전체 응답을 넣어야 맵이 온전하다.
+                    saveIndexSnapshotSafely(scope, projectId, data);
+                }
             }
             catch (error) {
                 // Error already handled by client interceptor (exitCode/stderr).
@@ -329,9 +509,16 @@ function registerSkillsCommand(program) {
         .description('스킬 단건 조회 — SKILL.md 본문 + 파일 매니페스트, --file 로 개별 파일만')
         .option('--global', '글로벌(팀 공유) 스킬. 생략 시 프로젝트 스킬(대상 프로젝트는 --project <id>/.ch-project/config)')
         .option('--file <path>', '지목한 개별 파일만 반환(스킬 폴더 기준 상대경로). 기본은 파일 원본을 stdout 으로, --json 이면 {scope,name,path,mime,content} JSON')
+        .option('--raw', 'SKILL.md 본문만 stdout 으로(메타 표·구분선 없음). --json 이면 {scope,name,content} JSON')
         .action(async (name, options) => {
         const globalOpts = program.opts();
         const scope = resolveScope(options);
+        // --file 은 이미 원본을 그대로 내보내므로 --raw 와 겹친다. 어느 쪽이
+        // 이겼는지 침묵으로 넘기지 않고 명시적으로 거부한다.
+        if (options.raw && options.file) {
+            (0, output_1.failInput)('--raw 와 --file 은 함께 쓸 수 없습니다. SKILL.md 본문은 --raw, 개별 파일 원본은 --file 만으로 얻습니다.');
+            return;
+        }
         try {
             const client = (0, client_1.createClient)({ projectId: globalOpts.project });
             // 서버 엔드포인트는 문서 id 를 받으므로 name→id 를 목록에서 해석한다.
@@ -368,12 +555,137 @@ function registerSkillsCommand(program) {
             }
             // 단건 — SKILL.md 본문 + files 매니페스트.
             const { data } = await client.get(`${skillBasePath(scope)}/${id}`);
+            if (options.raw) {
+                // 본문만 — 메타 표·`── 섹션 ──` 구분선 없이(에이전트가 그대로 소비).
+                // 기계 모드에서는 stdout 이 순수 JSON 하나여야 하므로 --file 과 같은
+                // 방식으로 봉투를 씌운다(1.x 출력 계약).
+                if ((0, output_1.isMachineMode)()) {
+                    (0, output_1.formatOutput)({ scope, name, content: data?.content ?? '' }, globalOpts);
+                }
+                else {
+                    process.stdout.write(data?.content ?? '');
+                }
+                return;
+            }
             (0, output_1.formatOutput)(data, globalOpts);
         }
         catch (error) {
             // Error already handled by client interceptor
         }
     });
+    // ch skills use <name> [--global|--project] [--refresh]
+    skills
+        .command('use <name>')
+        .description('스킬을 로컬 캐시에 적재하고 SKILL.md 본문을 출력 — 캐시가 최신이면 네트워크 없이, 바뀌었으면 그 스킬만 다시 받는다')
+        .option('--global', '글로벌(팀 공유) 스킬. 생략 시 프로젝트 스킬(대상 프로젝트는 --project <id>/.ch-project/config)')
+        .option('--refresh', '목록 스냅샷을 무시하고 서버에서 신선도를 다시 확인(방금 서버에서 고쳤을 때)')
+        .action(async (name, options) => {
+        const globalOpts = program.opts();
+        const scope = resolveScope(options);
+        const projectId = (0, config_1.getProjectContext)(globalOpts.project)?.projectId ?? null;
+        // 프로젝트 스킬은 프로젝트마다 같은 이름이 있을 수 있어 캐시 키에
+        // projectId 가 필요하다. 미해석이면 어느 캐시인지부터 정할 수 없다.
+        if (scope === 'project' && !projectId) {
+            (0, output_1.failInput)('프로젝트가 선택되지 않았습니다. --project <projectId> 를 지정하거나 .ch-project / ~/.ch/config.json 에 projectId 를 설정하세요. 팀 공유 스킬이면 --global 을 붙이세요.');
+            return;
+        }
+        const target = { scope, projectId, name };
+        const cached = (0, skills_cache_1.readCachedSkill)(target);
+        const viewOf = (content, source, stored) => ({
+            scope,
+            name,
+            content,
+            dir: stored?.dir ?? null,
+            files: stored?.files ?? [],
+            source,
+        });
+        /**
+         * 조회가 막혔을 때의 출구 — 캐시본으로 진행하고 경고만 남긴다(fail-open).
+         * 스킬 본문은 CLI 가 스스로 받아올 수 있는 것이지 사람이 손대야 하는 게
+         * 아니므로, 못 받았다고 명령을 실패로 끝내지 않는다. 캐시조차 없으면
+         * 줄 게 없으니 그때는 호출측이 실패로 끝낸다.
+         */
+        const fallBackToCache = (reason) => {
+            const content = cached ? (0, skills_cache_1.readCachedManifest)(target) : null;
+            if (!cached || content === null)
+                return false;
+            stderrNote(`${reason} 캐시본으로 진행합니다 (캐시 시각 ${cached.cachedAt}).`, 'warn');
+            emitSkill(viewOf(content, 'cache', cached), globalOpts);
+            return true;
+        };
+        /** 서버도 캐시도 줄 게 없을 때의 종료 — 두 자리에서 같은 문장을 쓴다. */
+        const failNoSource = (reason) => {
+            (0, output_1.failInput)(`스킬 "${name}"(${scope})을(를) 받을 수 없고 로컬 캐시에도 없습니다: ${reason}`);
+        };
+        const client = (0, client_1.createProbeClient)({
+            projectId: globalOpts.project,
+            timeout: SKILL_FETCH_TIMEOUT_MS,
+        });
+        if (!client) {
+            if (fallBackToCache('API Key 가 없어 서버를 조회하지 못했습니다.')) {
+                return;
+            }
+            (0, output_1.failInput)('API Key가 설정되지 않았습니다. "ch auth login" 명령어로 로그인하세요.');
+            return;
+        }
+        // 1) 신선도 맵 — 세션 스냅샷이 살아 있으면 서버를 묻지 않는다(추가 조회 0회).
+        //    스냅샷에 이름이 없으면(그새 등록된 스킬일 수 있다) 서버를 한 번 읽는다.
+        let entry = options.refresh
+            ? undefined
+            : (0, skills_cache_1.readIndexSnapshot)(scope, projectId)?.entries[name];
+        if (!entry) {
+            try {
+                const rows = await fetchSkillIndex(client, scope);
+                saveIndexSnapshotSafely(scope, projectId, rows);
+                entry = indexEntryOf(rows, name);
+            }
+            catch (error) {
+                const reason = describeRequestFailure(error);
+                if (fallBackToCache(`서버 목록을 읽지 못했습니다(${reason}).`))
+                    return;
+                failNoSource(reason);
+                return;
+            }
+        }
+        if (!entry) {
+            // 목록은 읽혔는데 그 이름이 없다 — 조회 실패가 아니라 없는 스킬이다.
+            // 낡은 캐시본을 최신인 척 내보내지 않고 실패로 알린다.
+            (0, output_1.failInput)(`스킬을 찾을 수 없습니다: "${name}" (${scope}). 목록은 ch skills list 로 확인하세요.` +
+                (cached ? ' 로컬 캐시에는 남아 있지만 서버 목록에는 없습니다.' : ''));
+            return;
+        }
+        // 2) 캐시 적중 — 토큰이 같으면 받지 않고 그대로 낸다.
+        if ((0, skills_cache_1.isFresh)(cached, entry.token)) {
+            const content = (0, skills_cache_1.readCachedManifest)(target);
+            if (content !== null) {
+                emitSkill(viewOf(content, 'cache', cached), globalOpts);
+                await pingSkillUsage(client, scope, entry.id);
+                return;
+            }
+        }
+        // 3) 캐시에 없거나 낡았으면 그 스킬만 받아서 캐시한다.
+        let payload;
+        try {
+            payload = await downloadSkill(client, scope, entry);
+        }
+        catch (error) {
+            const reason = describeRequestFailure(error);
+            if (fallBackToCache(`스킬을 내려받지 못했습니다(${reason}).`))
+                return;
+            failNoSource(reason);
+            return;
+        }
+        let stored = null;
+        try {
+            stored = (0, skills_cache_1.writeCachedSkill)(target, payload);
+        }
+        catch (e) {
+            // 받아온 본문은 이미 손에 있다 — 저장만 실패했다고 출력까지 접지 않는다.
+            stderrNote(`캐시에 저장하지 못했습니다(${e?.message ?? e}). 이번에는 받은 본문만 출력합니다.`, 'warn');
+        }
+        emitSkill(viewOf(payload.content, 'download', stored), globalOpts);
+        await pingSkillUsage(client, scope, entry.id);
+    });
     // ch skills register <dir> --global|--project
     skills
         .command('register <dir>')
@@ -459,5 +771,398 @@ function registerSkillsCommand(program) {
             // Error already handled
         }
     });
+    // ch skills delete <name> --global|--project [--yes]
+    skills
+        .command('delete <name>')
+        .description('스킬 삭제 (파괴적) — 문서와 저장된 파일을 함께 제거')
+        .option('--global', '글로벌(팀 공유) 스킬. 생략 시 프로젝트 스킬(대상 프로젝트는 --project <id>/.ch-project/config)')
+        .option('--yes', '확인 없이 바로 삭제(스크립트·에이전트용)')
+        .action(async (name, options) => {
+        const globalOpts = program.opts();
+        const scope = resolveScope(options);
+        try {
+            const client = (0, client_1.createClient)({ projectId: globalOpts.project });
+            // 서버 DELETE 는 문서 id 를 받으므로 name→id 를 목록에서 해석한다.
+            // 없는 이름이면 여기서 끝난다 — 확인 프롬프트로 사람을 붙잡지 않는다.
+            const { data: list } = await client.get(skillBasePath(scope));
+            const id = findSkillIdByName(Array.isArray(list) ? list : [], name);
+            if (!id) {
+                (0, output_1.failInput)(`삭제할 스킬을 찾을 수 없습니다: "${name}" (${scope}). 목록은 ch skills list 로 확인하세요.`);
+                return;
+            }
+            if (globalOpts.dryRun) {
+                (0, output_1.printInfo)(`[DRY-RUN] 스킬 "${name}"(${scope}) 삭제 요청`);
+                return;
+            }
+            const plan = planConfirmation({
+                yes: options.yes,
+                // 기계 모드(--json)는 사람이 답할 자리가 아니므로 대화형에서 제외한다.
+                interactive: !!process.stdin.isTTY && !(0, output_1.isMachineMode)(),
+            });
+            if (plan === 'refuse') {
+                (0, output_1.failInput)(`삭제 확인을 받을 수 없습니다(비대화형). 스킬 "${name}"(${scope})을(를) 지우려면 --yes 를 붙이세요.`);
+                return;
+            }
+            if (plan === 'prompt') {
+                const confirmed = await askConfirmation(`스킬 "${name}"(${scope})을(를) 삭제합니다. 파일까지 함께 지워지며 되돌릴 수 없습니다. 계속할까요? (y/N) `);
+                if (!confirmed) {
+                    // 사람이 스스로 그만둔 것이므로 실패가 아니다(exit 0).
+                    (0, output_1.printWarning)('삭제를 취소했습니다. 아무것도 지우지 않았습니다.');
+                    return;
+                }
+            }
+            // 인가(글로벌=systemAdmin, 프로젝트=admin·developer)는 서버가 판정한다.
+            const { data } = await client.delete(`${skillBasePath(scope)}/${id}`);
+            // 서버에서 지운 스킬이 로컬 캐시에 유령으로 남으면 `use` 가 없는 스킬의
+            // 본문을 계속 내준다. 삭제가 성공한 자리에서 캐시도 함께 회수한다.
+            let cacheReclaimed = false;
+            try {
+                cacheReclaimed = (0, skills_cache_1.removeCachedSkill)({
+                    scope,
+                    projectId: (0, config_1.getProjectContext)(globalOpts.project)?.projectId ?? null,
+                    name,
+                });
+            }
+            catch {
+                // 로컬 캐시 정리 실패가 서버 삭제 결과를 뒤집지는 않는다.
+            }
+            // 기계 모드에서는 서버 응답을 stdout 에 순수 JSON 으로 남겨 JSON.parse 가
+            // 되게 한다. 사람용(표) 모드에서는 성공 한 줄이면 충분하다.
+            if ((0, output_1.isMachineMode)())
+                (0, output_1.formatOutput)(data, globalOpts);
+            (0, output_1.printSuccess)(`스킬 "${name}"이(가) 삭제되었습니다 (${scope}).` +
+                (cacheReclaimed ? ' 로컬 캐시도 회수했습니다.' : ''));
+        }
+        catch (error) {
+            // Error already handled by client interceptor (403·404 등)
+        }
+    });
+    // ch skills sync --full [--scope global|project|all] [--prune]
+    skills
+        .command('sync')
+        .description('공유스킬 본문을 전량 로컬 캐시에 내려받아 로컬 검색을 가능하게 한다 — 목록 1회로 대조해 바뀐 것만 받는다')
+        .option('--full', '전량 동기화(현재 유일한 모드). 무거운 작업이라 명시적으로 켠다')
+        .option('--scope <scope>', '동기화할 스코프: global | project | all (기본 all — 글로벌+프로젝트)', 'all')
+        .option('--prune', '서버 목록에 없는 스킬의 캐시를 제거')
+        .action(async (options) => {
+        await runSkillsSync(options, program.opts());
+    });
+    // ch skills diff [--local <dir>] [--global]
+    skills
+        .command('diff')
+        .description('서버 공유스킬과 로컬 사본을 대조해 어느 쪽이 최신인지 판정 — 판정만 한다(삭제·업로드 없음)')
+        .option('--global', '글로벌(팀 공유) 스킬만 대조. 생략 시 글로벌+프로젝트를 함께 대조(로컬 폴더에는 스코프 표시가 없어 한쪽만 보면 오분류된다)')
+        .option('--local <dir>', '대조할 로컬 스킬 폴더(기본: ~/.claude/skills). 읽기만 한다.')
+        .action(async (options) => {
+        const globalOpts = program.opts();
+        const projectId = (0, config_1.getProjectContext)(globalOpts.project)?.projectId ?? null;
+        const localDir = path.resolve(options.local ?? (0, skills_diff_1.defaultLocalSkillsDir)());
+        // 로컬 폴더는 읽기 전용 대상이다. 사용자가 지목한 경로가 없으면 오타일
+        // 가능성이 크니 실패로 알리고, 기본 경로가 없으면 "사본이 없는 상태"로 본다.
+        const localExists = isDirectory(localDir);
+        if (!localExists) {
+            if (options.local) {
+                (0, output_1.failInput)(`로컬 스킬 폴더를 찾을 수 없습니다: ${localDir}`);
+                return;
+            }
+            (0, output_1.printWarning)(`로컬 스킬 폴더가 없습니다(${localDir}) — 로컬 사본이 없는 것으로 보고 대조합니다.`);
+        }
+        const { copies, skipped } = localExists
+            ? (0, skills_diff_1.scanLocalSkills)(localDir, (md) => parseSkillFrontmatter(md).name)
+            : { copies: [], skipped: [] };
+        // 스킬 폴더 하나를 직접 가리킨 경우 — 하위에 스킬이 없어 "로컬 사본 없음"으로
+        // 보인다. 그 침묵이 곧 오답이므로(사본이 있는데 없다고 읽힌다) 짚어 준다.
+        if (copies.length === 0 &&
+            localExists &&
+            fs.existsSync(path.join(localDir, exports.SKILL_MANIFEST_FILENAME))) {
+            (0, output_1.printWarning)('지정한 폴더 자체가 스킬 폴더입니다(SKILL.md 가 있습니다) — 스킬들을 담은 상위 폴더를 지정하세요.');
+        }
+        const client = (0, client_1.createClient)({ projectId: globalOpts.project });
+        const serverEntries = [];
+        const scanned = [];
+        for (const scope of scopesToList(options)) {
+            if (scope === 'project' && !projectId) {
+                (0, output_1.printWarning)('프로젝트가 정해지지 않아 프로젝트 스킬은 건너뜁니다(--project <id> / .ch-project). 팀 공유 스킬만 대조합니다.');
+                continue;
+            }
+            try {
+                const rows = await fetchSkillIndex(client, scope);
+                saveIndexSnapshotSafely(scope, projectId, rows);
+                serverEntries.push(...rows.map((row) => toServerEntry(scope, row)));
+                scanned.push(scope);
+            }
+            catch {
+                // 반쪽 목록으로 판정하면 서버에 있는 스킬이 "로컬에만 있음"으로 뒤집혀
+                // 사람이 지우면 안 될 것을 지우게 된다. 그래서 대조를 접는다.
+                (0, output_1.failInput)(`서버 스킬 목록(${scope})을 읽지 못해 대조를 중단합니다 — 반쪽 목록으로 판정하면 로컬 사본을 잘못 정리하게 됩니다.`);
+                return;
+            }
+        }
+        // 본문은 겹치는 스킬만 받는다(로컬 사본이 없는 스킬은 본문이 필요 없다).
+        const localKeys = new Set(copies.flatMap(skills_diff_1.localMatchKeys));
+        const manifests = new Map();
+        for (const entry of serverEntries) {
+            if (!localKeys.has((0, skills_diff_1.normalizeSkillKey)(entry.name)))
+                continue;
+            manifests.set((0, skills_diff_1.manifestKey)(entry), await loadServerManifest(client, entry, projectId));
+        }
+        const result = (0, skills_diff_1.buildDiffResult)({
+            localDir,
+            scopes: scanned,
+            serverEntries,
+            localCopies: copies,
+            skipped,
+            manifests,
+        });
+        if ((0, output_1.isMachineMode)())
+            (0, output_1.formatOutput)(result, globalOpts);
+        else
+            console.log((0, skills_diff_1.renderDiffReport)(result));
+    });
+}
+// ── sync --full (SKILL-016) ───────────────────────────────────────────────
+//
+// 목록은 이름·설명 인덱스만 준다. 본문은 GCS 에 있어 서버 전문검색이 없으므로
+// "어떤 스킬이 무엇을 참조하나" 같은 질문에 스킬 수만큼의 조회가 들었다. 전량을
+// 캐시해 두면 같은 질문이 로컬 파일 검색 한 번으로 끝난다.
+//
+// `use` 가 스킬 1건에 하는 일(목록으로 신선도 확인 → 낡았으면 그것만 재다운로드)
+// 을 전량으로 넓힌 것뿐이다 — 저장소·신선도 규칙은 `use` 와 같은 것을 쓴다.
+/**
+ * `--scope` 값을 훑을 스코프 목록으로 바꾼다. 기본(값 없음)은 글로벌+프로젝트 —
+ * `list` 의 기본과 같은 합집합이다(로컬 검색은 둘 다 있어야 온전하다).
+ * 알 수 없는 값이면 null 을 돌려 호출측이 입력 오류로 끝내게 한다.
+ */
+function parseSyncScopes(value) {
+    const normalized = (value ?? 'all').trim().toLowerCase();
+    if (normalized === '' || normalized === 'all')
+        return ['global', 'project'];
+    if (normalized === 'global')
+        return ['global'];
+    if (normalized === 'project')
+        return ['project'];
+    return null;
+}
+/**
+ * 한 스코프를 동기화한다 — 목록 1회 → 캐시 대조 → 바뀐 것만 다운로드.
+ *
+ * 개별 스킬의 실패로 전체를 중단하지 않는다. 52개 중 1개가 막혔다고 나머지를
+ * 포기하면 다음 실행이 또 전량을 받아야 한다. 실패는 세어 두었다가 종료코드로 알린다.
+ */
+async function syncSkillScope(client, scope, projectId, opts) {
+    const result = {
+        scope,
+        projectId,
+        total: 0,
+        downloaded: 0,
+        upToDate: 0,
+        pruned: 0,
+        failed: 0,
+    };
+    let rows;
+    try {
+        rows = await fetchSkillIndex(client, scope);
+    }
+    catch (error) {
+        // 목록을 못 읽으면 이 스코프는 대조할 근거가 없다. 특히 --prune 은 목록을
+        // 근거로 지우므로, 반쪽 정보로 멀쩡한 캐시를 지우지 않도록 통째로 건너뛴다.
+        result.error = describeRequestFailure(error);
+        (0, output_1.printWarning)(`${scope} 목록을 읽지 못해 건너뜁니다(${result.error}). 캐시는 그대로 둡니다.`);
+        return result;
+    }
+    // 이 목록이 곧 신선도 맵이다(SKILL-011). 저장해 두면 뒤이은 `ch skills use` 가
+    // 서버를 다시 묻지 않는다. dry-run 은 로컬 상태도 남기지 않는다 — 시뮬레이션이
+    // 뒤이은 명령의 신선도 판정을 바꾸면 그건 이미 시뮬레이션이 아니다.
+    if (!opts.dryRun)
+        saveIndexSnapshotSafely(scope, projectId, rows);
+    result.total = rows.length;
+    const serverNames = new Set();
+    let seen = 0;
+    for (const row of rows) {
+        seen += 1;
+        const name = typeof row?.name === 'string' ? row.name.trim() : '';
+        const id = row?.id ? String(row.id) : '';
+        if (!name || !id) {
+            // 이름이나 id 가 없는 항목은 받을 수도, 캐시 키를 만들 수도 없다.
+            result.failed += 1;
+            (0, output_1.printWarning)(`이름·id 가 없는 목록 항목을 건너뜁니다 (${scope}).`);
+            continue;
+        }
+        serverNames.add(name);
+        const target = { scope, projectId, name };
+        const token = (0, skills_cache_1.freshnessToken)(row);
+        // 토큰이 같으면 받지 않는다. 어느 한쪽이라도 토큰을 모르면 신선하다고 우기지
+        // 않고 다시 받는다 — `use` 와 같은 규칙이다.
+        if ((0, skills_cache_1.isFresh)((0, skills_cache_1.readCachedSkill)(target), token)) {
+            result.upToDate += 1;
+            continue;
+        }
+        if (opts.dryRun) {
+            result.downloaded += 1;
+            (0, output_1.printInfo)(`[DRY-RUN] (${seen}/${rows.length}) ${scope}/${name} 내려받기`);
+            continue;
+        }
+        try {
+            const payload = await downloadSkill(client, scope, { id, token });
+            (0, skills_cache_1.writeCachedSkill)(target, payload);
+            result.downloaded += 1;
+            (0, output_1.printInfo)(`(${seen}/${rows.length}) ${scope}/${name} — 파일 ${(payload.files?.length ?? 0) + 1}개 캐시`);
+        }
+        catch (error) {
+            result.failed += 1;
+            (0, output_1.printWarning)(`${scope}/${name} 을(를) 받아 캐시하지 못했습니다(${describeRequestFailure(error)}). 나머지는 계속합니다.`);
+        }
+    }
+    if (opts.prune) {
+        for (const cached of (0, skills_cache_1.listCachedSkills)()) {
+            if (cached.scope !== scope)
+                continue;
+            // 프로젝트 캐시는 프로젝트마다 따로 산다 — 지금 동기화한 프로젝트의 것만 본다.
+            if (scope === 'project' && cached.projectId !== projectId)
+                continue;
+            if (serverNames.has(cached.name))
+                continue;
+            if (opts.dryRun) {
+                result.pruned += 1;
+                (0, output_1.printInfo)(`[DRY-RUN] ${scope}/${cached.name} 캐시 제거`);
+                continue;
+            }
+            try {
+                if ((0, skills_cache_1.removeCachedSkill)({
+                    scope,
+                    projectId: cached.projectId,
+                    name: cached.name,
+                })) {
+                    result.pruned += 1;
+                    (0, output_1.printInfo)(`${scope}/${cached.name} — 서버에 없어 캐시에서 제거`);
+                }
+            }
+            catch (e) {
+                result.failed += 1;
+                (0, output_1.printWarning)(`${scope}/${cached.name} 캐시를 지우지 못했습니다(${e?.message ?? e}).`);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * `ch skills sync --full` 본체.
+ *
+ * 커맨드 등록부는 얇게 두고 실제 일은 여기서 한다(같은 파일을 여러 작업이 동시에
+ * 건드리므로 등록부는 최소로).
+ */
+async function runSkillsSync(options, globalOpts) {
+    // 전량 동기화는 스킬 수만큼 네트워크를 쓰는 무거운 작업이라 옵트인이다.
+    // 맨몸 `ch skills sync` 를 조용히 전량 실행으로 해석하지 않는다.
+    if (!options.full) {
+        (0, output_1.failInput)('ch skills sync 는 전량 동기화만 지원합니다 — "ch skills sync --full" 로 실행하세요. 스킬 1건만 필요하면 ch skills use <name> 를 쓰세요.');
+        return;
+    }
+    const requested = parseSyncScopes(options.scope);
+    if (!requested) {
+        (0, output_1.failInput)(`--scope 값이 올바르지 않습니다: "${options.scope}". global | project | all 중 하나여야 합니다.`);
+        return;
+    }
+    const projectId = (0, config_1.getProjectContext)(globalOpts.project)?.projectId ?? null;
+    // 프로젝트 스킬은 프로젝트마다 같은 이름이 있을 수 있어 캐시 키에 projectId 가
+    // 필요하다. 미해석이면 어느 캐시인지부터 정할 수 없어 그 스코프는 돌 수 없다.
+    const scopes = requested.filter((scope) => scope !== 'project' || projectId);
+    if (scopes.length === 0) {
+        (0, output_1.failInput)('프로젝트가 선택되지 않았습니다. --project <projectId> 를 지정하거나 .ch-project / ~/.ch/config.json 에 projectId 를 설정하세요. 팀 공유 스킬만 받으려면 --scope global 을 쓰세요.');
+        return;
+    }
+    if (scopes.length < requested.length) {
+        // 기본(all)으로 왔는데 프로젝트가 없는 경우다 — 글로벌은 받을 수 있으므로
+        // 실패로 끝내지 않고 받을 수 있는 것만 받는다.
+        (0, output_1.printWarning)('프로젝트가 선택되지 않아 글로벌 스킬만 동기화합니다. 프로젝트 스킬도 받으려면 --project <projectId> 를 지정하세요.');
+    }
+    const client = (0, client_1.createProbeClient)({
+        projectId: globalOpts.project,
+        timeout: SKILL_FETCH_TIMEOUT_MS,
+    });
+    if (!client) {
+        (0, output_1.failInput)('API Key가 설정되지 않았습니다. "ch auth login" 명령어로 로그인하세요.');
+        return;
+    }
+    const dryRun = !!globalOpts.dryRun;
+    const results = [];
+    for (const scope of scopes) {
+        // 스코프는 차례로 돈다. 스킬도 차례로 받는다 — 서버를 동시에 두드리지 않고,
+        // 무거운 건 어차피 최초 1회뿐이다.
+        results.push(await syncSkillScope(client, scope, scope === 'global' ? null : projectId, { prune: !!options.prune, dryRun }));
+    }
+    const sum = (pick) => results.reduce((acc, r) => acc + pick(r), 0);
+    const failedScopes = results.filter((r) => r.error);
+    const summary = {
+        scanned: sum((r) => r.total),
+        downloaded: sum((r) => r.downloaded),
+        upToDate: sum((r) => r.upToDate),
+        pruned: sum((r) => r.pruned),
+        failed: sum((r) => r.failed),
+        dryRun,
+        // 캐시 폴더를 알려 준다 — 이 명령의 목적이 이 폴더에서의 로컬 검색이다.
+        cacheDir: (0, skills_cache_1.cacheRoot)(),
+        scopes: results,
+    };
+    (0, output_1.formatOutput)(summary, globalOpts);
+    if (!(0, output_1.isMachineMode)()) {
+        (0, output_1.printInfo)(`로컬 검색은 이 폴더에서: ${(0, skills_cache_1.cacheRoot)()}`);
+    }
+    if (summary.failed > 0 || failedScopes.length > 0) {
+        // 반쪽 동기화를 성공으로 보고하지 않는다 — 부른 쪽이 종료코드만으로 알 수 있게.
+        (0, output_1.failInput)(`동기화를 마쳤지만 실패가 있습니다 — 스킬 ${summary.failed}건${failedScopes.length
+            ? `, 스코프 ${failedScopes.map((r) => r.scope).join('·')}`
+            : ''}. 다시 실행하면 실패한 것만 받습니다.`);
+        return;
+    }
+    (0, output_1.printSuccess)(`스킬 캐시 동기화 완료 — 조회 ${summary.scanned}건 중 ${dryRun ? '받을 것' : '내려받음'} ${summary.downloaded}건, 최신 ${summary.upToDate}건` +
+        (options.prune ? `, 정리 ${summary.pruned}건` : ''));
+}
+// ── diff 보조 (SKILL-012) ─────────────────────────────────────────────────
+/** 경로가 폴더인지. 접근할 수 없으면 폴더가 아닌 것으로 본다. */
+function isDirectory(target) {
+    try {
+        return fs.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** 목록 응답 한 줄을 대조용 항목으로 좁힌다(신선도 토큰 = updatedAt ?? createdAt). */
+function toServerEntry(scope, row) {
+    return {
+        scope,
+        id: String(row?.id ?? ''),
+        name: String(row?.name ?? ''),
+        token: (0, skills_cache_1.freshnessToken)(row),
+        fileCount: typeof row?.fileCount === 'number' ? row.fileCount : null,
+    };
+}
+/**
+ * 대조할 서버 본문을 얻는다 — 캐시가 신선하면 캐시본(네트워크 0), 아니면 단건 조회.
+ *
+ * 캐시는 **읽기만** 한다. 여기서 받은 본문을 캐시에 적재하면 번들 파일 없이 레코드가
+ * 생겨 뒤이은 `use` 가 반쪽 폴더를 최신인 양 내주게 된다(캐시 계약은 폴더 통째 교체다).
+ * 본문을 못 받으면 null — 그 항목만 "판정 보류"가 되고 대조 전체는 계속된다.
+ */
+async function loadServerManifest(client, entry, projectId) {
+    const target = {
+        scope: entry.scope,
+        projectId,
+        name: entry.name,
+    };
+    if ((0, skills_cache_1.isFresh)((0, skills_cache_1.readCachedSkill)(target), entry.token)) {
+        const cachedManifest = (0, skills_cache_1.readCachedManifest)(target);
+        if (cachedManifest !== null)
+            return cachedManifest;
+    }
+    try {
+        const { data } = await client.get(`${skillBasePath(entry.scope)}/${entry.id}`);
+        return typeof data?.content === 'string' ? data.content : null;
+    }
+    catch {
+        // 인터셉터가 이미 사유를 알리고 exitCode 를 세웠다.
+        return null;
+    }
 }
 //# sourceMappingURL=skills.js.map