@rch4com/agent-setup 1.21.0 → 1.21.1

package/README.md

@@ -78,6 +78,14 @@ show up in `status` and can be pulled in later with `update --force`.
 
 ## Safety
 
+The rules below are what the **bootstrap** (`bootstrap`, `update`, `status`)
+upholds. The optional-item picker runs third-party installers, and its two
+`global.*` items (`global.superpowers`, `global.ponytail`) deliberately write
+to per-user CLI configuration under your home directory — the screen marks
+them as machine-global and `--set` never removes them. The full list of what
+each item runs is in the
+[usage guide](https://github.com/rch4com/Agent-Setup/blob/main/AgentSetup-README.md#what-the-installer-runs).
+
 - Runs only inside a Git repository, and never writes outside the repository root.
 - Never reads or modifies global configuration in your home directory.
 - Never overwrites existing configuration files.
@@ -176,6 +184,14 @@ npx @rch4com/agent-setup bootstrap --adopt
 
 ## 안전 원칙
 
+아래는 **부트스트랩**(`bootstrap`·`update`·`status`)이 지키는 규칙입니다.
+선택 항목 화면은 제3자 설치기를 실행하며, 그중 `global.*` 두 항목
+(`global.superpowers`, `global.ponytail`)은 의도적으로 홈 디렉터리 아래
+CLI별 사용자 설정에 씁니다 — 화면이 머신 전역임을 표시하고 `--set`은 이
+항목을 제거하지 않습니다. 항목마다 무엇을 실행하는지는
+[사용 안내](https://github.com/rch4com/Agent-Setup/blob/main/AgentSetup-README.ko.md#설치기가-실행하는-것)에
+있습니다.
+
 - 반드시 Git 저장소 안에서만 실행되며, 저장소 루트 밖에는 쓰지 않습니다.
 - 홈 디렉터리의 글로벌 설정을 읽거나 수정하지 않습니다.
 - 기존 설정 파일을 덮어쓰지 않습니다.

package/lib/args.mjs

@@ -17,7 +17,9 @@ export const designUsage = (t) => t('usage.design')
 export const updateUsage = (t) => t('usage.update')
 export const statusUsage = (t) => t('usage.status')
 
-const SKILL_MODES = ['auto', 'link', 'copy']
+// 허용값의 단일 출처. flow.mjs(실행 시 검증)와 record.mjs(기록 읽기)가 함께 쓴다 —
+// 셋이 따로 들고 있으면 한 곳에 값이 늘 때 나머지가 그 값을 거부한다.
+export const SKILL_MODES = ['auto', 'link', 'copy']
 
 // 인자 사양: 플래그 이름 → 'bool'(값 없음) | 'value'(값 하나를 소비).
 // 미지 인자를 조용히 삼키지 않기 위한 것이다 — 오타(`--dryrun`)나 지원하지

package/lib/bootstrap/apply.mjs

@@ -5,6 +5,7 @@ import { dirname } from 'node:path'
 import { repoPath, repoPathStrict } from '../context.mjs'
 import { ensureGitignoreEntries } from '../gitignore.mjs'
 import { createT, msg } from '../i18n/index.mjs'
+import { escapeRegExp } from '../untrusted.mjs'
 import { hashBody, normalizeBody } from './text.mjs'
 import { BEGIN_MARKER, END_MARKER, extractBlock, managedKey } from './record.mjs'
 import { configureAdapter } from './adapter.mjs'
@@ -231,12 +232,13 @@ export function ensureJsonKeys(root, entries, { dryRun = false, log, t = createT
       return { ok: true, action: 'warn', path: rel, message: msg('msg.readFailed') }
     }
 
-    // 주석 안에 있어도 건드리지 않는다 — 사용자가 언급한 키를 스크립트가
-    // 되살리지 않는 편이 "기존 설정을 덮어쓰지 않는다"는 원칙에 맞는다.
-    // 문자열 포함 검사라 키 이름이 어떤 값 안에 들어 있어도 건너뛴다. 보수적인
-    // 쪽으로 틀리는 것(넣지 않음)이라 파일을 망가뜨리지는 않는다. 정확히 하려면
-    // 최상위 키만 보는 파서가 필요한데, 부트스트랩은 의존성을 쓸 수 없다.
-    if (text.includes(JSON.stringify(key))) {
+    // 줄 머리에 `"키":` 꼴로 놓인 것만 "있음"으로 본다. 단순 문자열 포함
+    // 검사는 주석(`// see "chat.useAgentsMdFile"`)이나 다른 키의 값 안에 든
+    // 이름까지 "있음"으로 읽어, 키를 넣지 않고도 성공 로그를 냈다 — VS Code
+    // Copilot이 AGENTS.md를 영영 읽지 못하는데 화면은 성공이다. 정확히 하려면
+    // 최상위 키만 보는 파서가 필요한데 부트스트랩은 의존성을 쓸 수 없다 —
+    // 중첩 객체 안의 같은 키를 최상위로 오판하는 쪽(넣지 않음)으로만 틀린다.
+    if (new RegExp(`^\\s*${escapeRegExp(JSON.stringify(key))}\\s*:`, 'm').test(text)) {
       log(t('log.json.keep', { path: rel, key }))
       return { ok: true, action: 'skip', path: rel }
     }

package/lib/bootstrap/flow.mjs

@@ -5,11 +5,10 @@ import {
   configureAdapterSafe, ensureBlocks, ensureDirs, ensureFiles, ensureIgnore, ensureJsonKeys,
 } from './apply.mjs'
 import { RECORD_REL, collectManaged, emptyRecord, readRecord, writeRecord } from './record.mjs'
+import { SKILL_MODES } from '../args.mjs'
 import { createT, LocalizedError, toText } from '../i18n/index.mjs'
 import { width } from '../width.mjs'
 
-const SKILL_MODES = ['auto', 'link', 'copy']
-
 // 오른쪽 정렬. width.mjs의 pad()는 오른쪽에 공백을 채워 왼쪽 정렬만 하므로
 // 숫자에는 못 쓴다 — 자릿수가 9에서 10으로 늘 때 열이 흔들리지 않으려면
 // 왼쪽에 채워야 한다. 숫자만 다루니 실제로는 문자 수와 같지만, 이 저장소의

package/lib/bootstrap/record.mjs

@@ -10,6 +10,7 @@
 // 부트스트랩 그래프에 속하므로 node: 내장 모듈만 쓴다.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
+import { SKILL_MODES } from '../args.mjs'
 import { repoPath, repoPathStrict } from '../context.mjs'
 import { LOCALES, LocalizedError } from '../i18n/index.mjs'
 import { hashBody, normalizeBody } from './text.mjs'
@@ -66,12 +67,14 @@ export function readRecord(root) {
   return {
     formatVersion: parsed.formatVersion,
     pinnedVersion: parsed.pinnedVersion ?? null,
-    skillMode: parsed.skillMode ?? 'auto',
     // 손으로 편집된 값 때문에 도구가 죽으면 안 된다. 모르는 값은 없는 것으로 본다.
+    // skillMode도 같다 — 걸러 두지 않으면 update가 그 값을 어댑터까지 흘려보낸다.
+    skillMode: SKILL_MODES.includes(parsed.skillMode) ? parsed.skillMode : 'auto',
     lang: LOCALES.includes(parsed.lang) ? parsed.lang : null,
     items: Array.isArray(parsed.items) ? parsed.items : [],
     design: Array.isArray(parsed.design) ? parsed.design : [],
-    managed: parsed.managed && typeof parsed.managed === 'object' ? parsed.managed : {},
+    // 배열도 typeof가 object다 — managed[rel] 조회가 undefined만 돌려주는 빈 껍데기가 된다.
+    managed: parsed.managed && typeof parsed.managed === 'object' && !Array.isArray(parsed.managed) ? parsed.managed : {},
   }
 }
 

package/lib/catalog.mjs

@@ -7,6 +7,9 @@ import { CLIS, CLI_IDS, MCP_CLI_IDS } from './clis.mjs'
 import { isPluginEnabled, enablePlugin, disablePlugin } from './claude-plugins.mjs'
 import { repoPath, repoPathStrict } from './context.mjs'
 import { LocalizedError, msg } from './i18n/index.mjs'
+// design-md가 아니라 잎 모듈에서 가져온다 — deps.test.mjs의 "의존성 없는
+// 트리"는 design-md를 통째로 빼고 --list를 돌린다(bootstrap.isolation.test.mjs).
+import { escapeRegExp, isSafeSegment } from './untrusted.mjs'
 
 const ITEMS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'items')
 
@@ -240,11 +243,18 @@ function findSkillDir(root, skill) {
     const file = join(base, name, 'SKILL.md')
     if (!existsSync(file)) continue
     const head = readFileSync(file, 'utf8').slice(0, 2000)
-    if (new RegExp(`^name:\\s*['"]?${skill}['"]?\\s*$`, 'm').test(head)) return name
+    if (new RegExp(`^name:\\s*['"]?${escapeRegExp(skill)}['"]?\\s*$`, 'm').test(head)) return name
   }
   return null
 }
 
+// 잠금 파일의 이름은 상류 SKILL.md frontmatter에서 온다 — 신뢰 경계 밖이다.
+// `npx skills remove <이름>`의 인자이자 `.agents/skills/<이름>` 경로가 되므로,
+// 플래그로 읽히는 선행 대시와 경로 구분자·상위 이동은 어느 쪽으로도 쓸 수 없다.
+function isSafeSkillName(name) {
+  return isSafeSegment(name) && !name.startsWith('-')
+}
+
 // 레지스트리가 저장소 루트에 남기는 잠금 파일. 스킬 이름마다 어느 출처에서
 // 왔는지를 적어 두므로, 한 상류가 여러 스킬을 깔았을 때 "우리가 넣은 것"만
 // 골라 지울 수 있는 유일한 근거다.
@@ -321,6 +331,9 @@ export function defineRegistrySkill({ id, label, source, skill, anchor = null, n
       const names = skill === '*' ? lockedSkills(root, source) : [skill]
       const targets = names.length > 0 ? names : [probe]
       for (const name of targets) {
+        // 인자·경로로 쓸 수 없는 이름은 건너뛴다. 잠금 항목은 아래 pruneLock이
+        // 함께 지운다 — 남기면 다음 제거가 같은 자리에서 또 멈춘다.
+        if (!isSafeSkillName(name)) continue
         // 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리를
         // 남긴다(실측). 그래서 성공/실패와 무관하게 남은 디렉터리를 우리가 지운다 —
         // 남겨 두면 detect가 계속 installed로 읽어 제거가 안 된 채 성공으로 보인다.

package/lib/deps.mjs

@@ -9,9 +9,11 @@ export async function withDeps(load, t) {
   try {
     return await load()
   } catch (err) {
-    // 모듈이 정말 없을 때만 안내로 바꾼다. 로드된 모듈 안에서 난 오류는
+    // 패키지가 정말 없을 때만 안내로 바꾼다. 로드된 모듈 안에서 난 오류는
     // 그대로 올려보내야 한다 — 삼키면 진짜 버그가 "의존성 없음"으로 둔갑한다.
-    if (err.code !== 'ERR_MODULE_NOT_FOUND') throw err
+    // 상대 경로 import 오타도 같은 코드로 오지만 Node는 문구로 가른다: 패키지
+    // 부재는 "Cannot find package", 파일 부재는 "Cannot find module".
+    if (err.code !== 'ERR_MODULE_NOT_FOUND' || !/Cannot find package/.test(err.message)) throw err
     throw new LocalizedError('error.depsMissing')
   }
 }

package/lib/design-md/catalog.mjs

@@ -5,6 +5,7 @@ import { createHash } from 'node:crypto'
 import { repoPath, repoPathStrict } from '../context.mjs'
 import { PROVIDERS, getProvider } from './providers/index.mjs'
 import { createT, LocalizedError } from '../i18n/index.mjs'
+import { isSafeSegment } from '../untrusted.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 export const CATALOG_PATH = join(HERE, 'catalog.json')
@@ -84,16 +85,11 @@ export async function netFetch(url, opts = {}) {
   }
 }
 
-// 경로 세그먼트 하나로 안전한 이름인지 본다. 한글 등 유니코드는 허용하되
-// 경로 구분자·상위 이동·Windows 금지 문자·제어문자는 막는다.
+// 경로 세그먼트 가드는 잎 모듈(lib/untrusted.mjs)에 있다 — lib/catalog.mjs도
+// 쓰는데 그쪽은 design-md에 정적으로 닿을 수 없다. 이 모듈의 소비자
+// (flow·scan·refresh-bundle)가 계속 여기서 가져갈 수 있게 다시 내보낸다.
 // (name은 원격 README 파싱이나 디렉터리 스캔에서 오므로 신뢰 경계 밖이다.)
-export function isSafeSegment(text) {
-  const value = String(text ?? '')
-  // 선행·후행 점은 숨김 파일이자 Windows에서 다루기 어려운 이름이다('.', '..' 포함).
-  if (!value || value.startsWith('.') || value.endsWith('.')) return false
-  // eslint-disable-next-line no-control-regex
-  return !/[\\/:*?"<>|\x00-\x1f]/.test(value)
-}
+export { isSafeSegment }
 
 // 라벨·카테고리·설명은 원격 README나 DESIGN.md 본문에서 온다. 목록과 TUI가
 // 이 값을 터미널에 그대로 찍으므로 제어문자를 걷어낸다 — ANSI 이스케이프가

package/lib/tomlfile.mjs

@@ -2,15 +2,12 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { parse } from 'smol-toml'
 import { LocalizedError } from './i18n/index.mjs'
+import { escapeRegExp } from './untrusted.mjs'
 
 function readText(file) {
   return existsSync(file) ? readFileSync(file, 'utf8') : ''
 }
 
-function escapeRegExp(text) {
-  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
 // 깨진 TOML은 읽기·쓰기 모두 거부한다. 예전에는 파싱 실패를 "섹션 없음"으로
 // 돌려줘, 닫는 대괄호가 빠진 파일 끝에 같은 섹션이 하나 더 붙고 사용자는
 // 파일이 깨진 것을 끝까지 몰랐다 — jsonfile.mjs의 JSON 규칙과 같다.

package/lib/untrusted.mjs

@@ -0,0 +1,26 @@
+// 신뢰 경계 밖에서 온 문자열의 가드. 잎 모듈이다 — bootstrap/apply.mjs가
+// 쓰므로 의존성이 들어오면 npm install 없이 도는 부트스트랩
+// (bootstrap.isolation.test.mjs)이 깨지고, lib/catalog.mjs가 쓰므로 design-md
+// 아래에 두면 design-md를 뺀 "의존성 없는 트리"(deps.test.mjs)에서 --list가
+// 원시 "Cannot find module"로 죽는다.
+//
+// 이 저장소의 방어는 "쓰기 경로만 엄격 검사"인데, 그 규칙은 읽은 데이터가
+// 경로·명령 인자·정규식이 되는 자리를 각각 덮지는 않는다. 그래서 그 셋을
+// 한 곳에 모아 둔다 — 원격 README의 항목 이름, 잠금 파일의 스킬 이름,
+// 디렉터리 스캔의 폴더 이름이 전부 여기를 지난다.
+
+// 경로 세그먼트 하나로 안전한 이름인지 본다. 한글 등 유니코드는 허용하되
+// 경로 구분자·상위 이동·Windows 금지 문자·제어문자는 막는다.
+export function isSafeSegment(text) {
+  const value = String(text ?? '')
+  // 선행·후행 점은 숨김 파일이자 Windows에서 다루기 어려운 이름이다('.', '..' 포함).
+  if (!value || value.startsWith('.') || value.endsWith('.')) return false
+  // eslint-disable-next-line no-control-regex
+  return !/[\\/:*?"<>|\x00-\x1f]/.test(value)
+}
+
+// RegExp 본문에 넣기 전의 이스케이프. 잠금 파일의 스킬 이름처럼 상류에서 온
+// 문자열이 `(`를 품으면 RegExp 생성 자체가 던져 제거가 중간에 죽었다.
+export function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.21.0",
+  "version": "1.21.1",
   "description": "Repository-scoped bootstrap and optional-item installer for using multiple coding-agent CLIs in one repository | 여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",