@t3q-ui/design-system 0.0.0-stage → 1.56.1

package/cli/doctor.mjs

@@ -0,0 +1,200 @@
+/**
+ * t3q-design doctor — 설치·연결·규칙 상태를 검사하고 실패마다 조치를 알려 준다.
+ * ✓ ok · ! warn(실패 아님) · ✗ fail(종료 코드 1). 네트워크 불가는 warn — 사내망 밖에서도 나머지는 점검된다.
+ * "오래됨" 은 버전이 아니라 내용 비교다 (규칙이 안 바뀐 릴리즈에서 헛경고 없음).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import {
+  checkMcp,
+  checkRegistry,
+  CODEX_CONFIG,
+  CODEX_SKILL_DEST,
+  codexMcpUrlOf,
+  CSS_IMPORTS,
+  findCss,
+  hasFontsImport,
+  hasImportLine,
+  hasStylesImport,
+  major,
+  managedBlock,
+  MCP_SERVER,
+  mcpUrlOf,
+  MIN_NODE,
+  nodeMajor,
+  npmrcLines,
+  parseNpmrc,
+  PKG_NAME,
+  readInstalledVersion,
+  readText,
+  resolvePeerVersion,
+  RULES_FILE,
+  SKILL_DEST,
+  skillStale,
+} from './lib.mjs'
+
+const SETUP = 't3q-design setup'
+/** 사내 점검(GITLAB_TOKEN·Bearer 확인)은 GitLab npm 레지스트리 주소(`…/api/v4/…/packages/npm/`)에만 맞다 — npmjs·미러 값은 건너뛴다 */
+const GITLAB_NPM_RE = /\/api\/v4\/.+\/packages\/npm\/?$/
+
+/** @returns {Promise<Array<{ status: 'ok'|'warn'|'fail'|'info', msg: string, fix?: string }>>} */
+export async function doctor(cwd, { env = process.env, fetch: fetchImpl = globalThis.fetch } = {}) {
+  const results = []
+  const add = (status, msg, fix) => results.push(fix ? { status, msg, fix } : { status, msg })
+  const file = (rel) => path.join(cwd, rel)
+  const exists = (rel) => fs.existsSync(file(rel))
+
+  // 1. Node
+  const node = nodeMajor()
+  if (node >= MIN_NODE) add('ok', `Node ${process.versions.node}`)
+  else add('fail', `Node ${process.versions.node}`, `Node ${MIN_NODE} 이상 설치`)
+
+  // 2. 패키지 매니저 (락파일)
+  const pm = exists('pnpm-lock.yaml')
+    ? 'pnpm'
+    : exists('package-lock.json')
+      ? 'npm'
+      : exists('yarn.lock')
+        ? 'yarn'
+        : null
+  if (pm) add('ok', `패키지 매니저 ${pm}`)
+  else add('warn', '락파일 없음', 'pnpm install')
+
+  // 3~5. 사내 레지스트리 — 프로젝트 .npmrc 에 @t3q-ui:registry 줄이 있을 때만 그 주소로 점검한다
+  const npmrc = parseNpmrc(readText(file('.npmrc')))
+  let latest = null
+  if (npmrc.registry == null) add('info', '.npmrc 에 @t3q-ui:registry 없음 — 기본 레지스트리(npmjs)에서 설치')
+  else if (!GITLAB_NPM_RE.test(npmrc.registry))
+    add('info', '.npmrc 의 @t3q-ui:registry 가 GitLab npm 레지스트리가 아님 — 토큰·레지스트리 점검 생략')
+  else {
+    if (npmrc.auth) add('ok', '.npmrc 레지스트리 2줄')
+    else
+      add(
+        'fail',
+        '.npmrc 에 레지스트리 토큰 줄 없음',
+        `${SETUP} --registry ${npmrc.registry} 또는 직접 추가:\n${npmrcLines(npmrc.registry).join('\n')}`,
+      )
+    const token = env.GITLAB_TOKEN
+    if (token) add('ok', 'GITLAB_TOKEN')
+    else add('fail', 'GITLAB_TOKEN 미설정', '토큰 발급 후 export GITLAB_TOKEN=… (docs/INTERNAL_SETUP.md)')
+    if (token) {
+      const r = await checkRegistry(npmrc.registry, token, fetchImpl)
+      if (r.status === 'ok') {
+        latest = r.latest
+        add('ok', `GitLab 레지스트리 접근${latest ? ` (최신 ${latest})` : ''}`)
+      } else if (r.status === 'auth')
+        add(
+          'fail',
+          `레지스트리 토큰 거부 (${r.detail})`,
+          'read_api·read_registry 스코프로 토큰 재발급',
+        )
+      else if (r.status === 'notfound')
+        add('fail', '레지스트리 404', 'GitLab 프로젝트 접근 권한 확인')
+      else add('warn', `레지스트리 접근 불가 (${r.detail})`, '사내망/VPN 연결 확인')
+    }
+  }
+
+  // 6. 설치
+  const installed = readInstalledVersion(cwd)
+  if (!installed) {
+    add('fail', `${PKG_NAME} 미설치`, `pnpm add ${PKG_NAME}`)
+    return results
+  }
+  add('ok', `${PKG_NAME} ${installed}`)
+
+  // 7. 최신 버전
+  if (latest && latest !== installed)
+    add('warn', `업데이트 가능 ${installed} → ${latest}`, `pnpm up ${PKG_NAME} && ${SETUP}`)
+
+  // 8. peer
+  const react = resolvePeerVersion(cwd, 'react')
+  if (react) add('ok', `react ${react}`)
+  else add('fail', 'react 미해결', 'pnpm add react react-dom')
+  const tw = resolvePeerVersion(cwd, 'tailwindcss')
+  if (tw && major(tw) === 4) add('ok', `tailwindcss ${tw}`)
+  else if (tw) add('fail', `tailwindcss ${tw}`, 'TDS 는 Tailwind v4 필요 — README "Tailwind 설정"')
+  else add('fail', 'tailwindcss 미해결', 'pnpm add -D tailwindcss @tailwindcss/postcss postcss')
+  const ag = resolvePeerVersion(cwd, 'ag-grid-community')
+  if (ag && major(ag) >= 36) add('ok', `ag-grid-community ${ag}`)
+  else if (ag) add('warn', `ag-grid-community ${ag}`, '36 이상 권장 (33 은 axe critical 위반)')
+  else
+    add(
+      'warn',
+      'ag-grid-community 미해결',
+      '표(AgGridTable) 를 쓰면 pnpm add ag-grid-community ag-grid-react',
+    )
+
+  // 9. CSS
+  const { v4, v3 } = findCss(cwd)
+  if (v4.length === 0 && v3.length > 0)
+    add('fail', `Tailwind v3 CSS (${v3.join(', ')})`, 'v4 로 올린 뒤 setup')
+  else if (v4.length === 0)
+    add(
+      'fail',
+      "@import 'tailwindcss' 가 있는 CSS 없음",
+      `진입 CSS 에 추가:\n@import 'tailwindcss';\n${CSS_IMPORTS.join('\n')}`,
+    )
+  else {
+    const withStyles = v4.filter((rel) => hasStylesImport(readText(file(rel)) ?? ''))
+    if (withStyles.length === 0)
+      add(
+        'fail',
+        `CSS 에 TDS styles.css import 없음 (${v4.join(', ')})`,
+        v4.length === 1 ? SETUP : `하나 골라 추가:\n${CSS_IMPORTS[0]}`,
+      )
+    else {
+      add('ok', `CSS styles.css import (${withStyles.join(', ')})`)
+      if (!withStyles.some((rel) => hasFontsImport(readText(file(rel)) ?? '')))
+        add(
+          'warn',
+          'CSS 에 fonts.css import 없음',
+          `앱이 Pretendard 를 직접 로드하면(next/font 등) 무시. 아니면 추가:\n${CSS_IMPORTS[1]}`,
+        )
+    }
+  }
+
+  // 10·11. MCP
+  const url = mcpUrlOf(readText(file('.mcp.json')))
+  if (!url) add('info', `.mcp.json 에 ${MCP_SERVER} 없음 — Skill reference 로 동작`)
+  else {
+    add('ok', `.mcp.json ${MCP_SERVER} → ${url}`)
+    const m = await checkMcp(url, fetchImpl)
+    if (m.ok) add('ok', `Storybook MCP 응답${m.server ? ` (${m.server})` : ''}`)
+    else
+      add(
+        'warn',
+        `Storybook MCP 응답 없음 (${m.detail})`,
+        '사내망 필요. 로컬 Storybook 이면 t3q-design setup --mcp-url http://localhost:6006/mcp',
+      )
+  }
+
+  // 12. Skill
+  if (!exists(path.join(SKILL_DEST, 'SKILL.md'))) add('fail', `${SKILL_DEST}/ 없음`, SETUP)
+  else if (skillStale(file(SKILL_DEST)))
+    add('fail', `${SKILL_DEST}/ 오래됨 (패키지 ${installed} 와 다름)`, SETUP)
+  else add('ok', `${SKILL_DEST}/ (/tds)`)
+
+  // 12b. Codex 산출물 — 안 쓰는 팀도 있으므로 warn (setup 이 둘 다 쓴다)
+  if (!exists(path.join(CODEX_SKILL_DEST, 'SKILL.md')))
+    add('warn', `${CODEX_SKILL_DEST}/ 없음 (Codex 스킬)`, SETUP)
+  else if (skillStale(file(CODEX_SKILL_DEST)))
+    add('warn', `${CODEX_SKILL_DEST}/ 오래됨 (패키지 ${installed} 와 다름)`, SETUP)
+  else add('ok', `${CODEX_SKILL_DEST}/ (Codex 스킬)`)
+  const codexUrl = codexMcpUrlOf(readText(file(CODEX_CONFIG)))
+  if (!codexUrl) add('info', `${CODEX_CONFIG} 에 ${MCP_SERVER} 없음 — Skill reference 로 동작`)
+  else add('ok', `${CODEX_CONFIG} ${MCP_SERVER} → ${codexUrl}`)
+
+  // 13. AGENTS.md 블록
+  const block = managedBlock(readText(file('AGENTS.md')))
+  const rules = (readText(RULES_FILE) ?? '').trim()
+  if (!block) add('fail', 'AGENTS.md 에 TDS 블록 없음', SETUP)
+  else if (block.body.trim() !== rules) add('fail', 'AGENTS.md TDS 블록 오래됨', SETUP)
+  else add('ok', `AGENTS.md TDS 블록${block.version ? ` (v${block.version})` : ''}`)
+
+  // 14. CLAUDE.md
+  if (hasImportLine(readText(file('CLAUDE.md')))) add('ok', 'CLAUDE.md @AGENTS.md')
+  else add('fail', 'CLAUDE.md 에 @AGENTS.md 없음', SETUP)
+
+  return results
+}

package/cli/lib.mjs

@@ -0,0 +1,425 @@
+/**
+ * t3q-design CLI 의 상수와 순수 함수. setup.mjs / doctor.mjs 가 쓰고 cli.test.mjs 가 검증한다.
+ * 파일 쓰기는 writeIfChanged 하나로만 한다 (읽기 → 바꾸기 → 달라졌을 때만 쓰기).
+ */
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const PKG_NAME = '@t3q-ui/design-system'
+/**
+ * 소비 레포 .npmrc 의 두 줄. 토큰 값이 아니라 `${GITLAB_TOKEN}` 참조를 쓴다 — 커밋해도 된다.
+ * 레지스트리 주소는 패키지에 두지 않는다 — 사내 설치만 `setup --registry <url>` 로 넘기고 (docs/INTERNAL_SETUP.md), 없으면 .npmrc 를 건드리지 않는다.
+ */
+export const npmrcLines = (registry) => [
+  `@t3q-ui:registry=${registry}`,
+  `//${registry.replace(/^https?:\/\//, '')}:_authToken=\${GITLAB_TOKEN}`,
+]
+export const MCP_SERVER = 'tds-storybook'
+export const CSS_IMPORTS = [`@import '${PKG_NAME}/styles.css';`, `@import '${PKG_NAME}/fonts.css';`]
+
+/** 패키지 루트. 레포에서 돌리든 node_modules 안에서 돌리든 이 파일 기준 `..` 이다 (bin 심링크는 Node 가 realpath 로 푼다). */
+export const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+export const SKILL_SRC = path.join(PKG_DIR, 'skills', 'tds')
+export const RULES_FILE = path.join(SKILL_SRC, 'rules.md')
+export const SKILL_DEST = path.join('.claude', 'skills', 'tds')
+/** Codex 는 스킬을 `.agents/skills/`, MCP 를 프로젝트 `.codex/config.toml`(Codex 가 trust 한 프로젝트만)에서 읽는다 — https://developers.openai.com/codex/mcp */
+export const CODEX_SKILL_DEST = path.join('.agents', 'skills', 'tds')
+export const CODEX_CONFIG = path.join('.codex', 'config.toml')
+/** rules.md 는 AGENTS.md 블록이 되므로 Skill 폴더로는 복사하지 않는다 (소비 레포에 같은 내용 두 벌 금지). */
+const SKILL_SKIP = new Set(['rules.md'])
+
+export const MIN_NODE = 18
+
+// ----------------------------------------------------------------------------
+// 파일 유틸
+// ----------------------------------------------------------------------------
+
+export function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+export function readJson(file) {
+  const text = readText(file)
+  if (text == null) return null
+  return JSON.parse(text)
+}
+
+/** 내용이 같으면 쓰지 않는다. 반환: 'unchanged' | 'written' */
+export function writeIfChanged(file, next) {
+  if (readText(file) === next) return 'unchanged'
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, next)
+  return 'written'
+}
+
+export const ownVersion = () => readJson(path.join(PKG_DIR, 'package.json'))?.version ?? 'unknown'
+
+export const nodeMajor = () => Number(process.versions.node.split('.')[0])
+
+// ----------------------------------------------------------------------------
+// .npmrc
+// ----------------------------------------------------------------------------
+
+const splitLines = (text) => (text ?? '').split(/\r?\n/).map((l) => l.trim())
+
+/** { registry: @t3q-ui:registry 의 값(없으면 null), auth: 그 레지스트리의 토큰 줄이 있는가 } */
+export function parseNpmrc(text) {
+  const lines = splitLines(text)
+  const registry =
+    lines.find((l) => l.startsWith('@t3q-ui:registry='))?.slice('@t3q-ui:registry='.length) ?? null
+  const auth = registry != null && lines.some((l) => l.startsWith(npmrcLines(registry)[1].split('=')[0] + '='))
+  return { registry, auth }
+}
+
+/** 없는 줄만 뒤에 붙인다. 다른 값의 스코프 줄이 있으면 손대지 않는다. 반환 { text, conflict } */
+export function ensureNpmrc(text, registry) {
+  const want = npmrcLines(registry)
+  const state = parseNpmrc(text)
+  if (state.registry != null && state.registry !== registry) return { text: text ?? '', conflict: true }
+  const missing = [state.registry ? null : want[0], state.auth ? null : want[1]].filter(Boolean)
+  if (missing.length === 0) return { text, conflict: false }
+  const head = text ? text.replace(/\s*$/, '') + '\n' : ''
+  return { text: head + missing.join('\n') + '\n', conflict: false }
+}
+
+// ----------------------------------------------------------------------------
+// AGENTS.md 관리 블록 · CLAUDE.md import
+// ----------------------------------------------------------------------------
+
+/** 관리 블록 마커. md = HTML 주석(AGENTS.md), toml = `#` 주석(.codex/config.toml — TOML 에서 `<!--` 는 문법 오류) */
+const MARKERS = {
+  md: { open: '<!-- tds:start', close: '-->', end: '<!-- tds:end -->' },
+  toml: { open: '# tds:start', close: '', end: '# tds:end' },
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const blockRe = (kind) => {
+  const { open, close, end } = MARKERS[kind]
+  return new RegExp(
+    `${escapeRe(open)}([^\\n]*?)${escapeRe(close)}\\r?\\n([\\s\\S]*?)\\r?\\n${escapeRe(end)}`,
+  )
+}
+
+/** 블록이 있으면 { version, body } 없으면 null */
+export function managedBlock(text, kind = 'md') {
+  const m = blockRe(kind).exec(text ?? '')
+  if (!m) return null
+  return { version: /v(\S+)/.exec(m[1])?.[1] ?? null, body: m[2] }
+}
+
+/** 블록을 만들거나(없으면 끝에 추가) 교체한다. 블록 밖 내용은 그대로. */
+export function upsertManagedBlock(text, body, version, kind = 'md') {
+  const { open, close, end } = MARKERS[kind]
+  const block = `${[open, `v${version}`, close].filter(Boolean).join(' ')}\n${body.trim()}\n${end}`
+  if (managedBlock(text, kind)) return text.replace(blockRe(kind), () => block)
+  const head = text?.trim() ? text.replace(/\s*$/, '') + '\n\n' : ''
+  return head + block + '\n'
+}
+
+const IMPORT_RE = /^@AGENTS\.md\s*$/m
+
+export const hasImportLine = (text) => IMPORT_RE.test(text ?? '')
+
+/** CLAUDE.md 에 `@AGENTS.md` 한 줄을 보장한다. 있으면 그대로, 없으면 끝에 추가. */
+export function ensureImportLine(text) {
+  if (hasImportLine(text)) return text
+  const head = text?.trim() ? text.replace(/\s*$/, '') + '\n\n' : ''
+  return head + '@AGENTS.md\n'
+}
+
+// ----------------------------------------------------------------------------
+// CSS 진입 파일
+// ----------------------------------------------------------------------------
+
+const PRUNE = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  '.next',
+  '.git',
+  'coverage',
+  'storybook-static',
+])
+const TW4_RE = /^[ \t]*@import\s+["']tailwindcss["'][^\r\n]*$/m
+const TW3_RE = /^[ \t]*@tailwind\s+base\b/m
+const HAS_STYLES_RE = /@import\s+["']@t3q-ui\/design-system\/styles\.css["']/
+const HAS_FONTS_RE = /@import\s+["']@t3q-ui\/design-system\/fonts\.css["']/
+
+/** cwd 아래 .css 를 훑어 { v4: [`@import 'tailwindcss'` 가 있는 파일], v3: [`@tailwind base` 가 있는 파일] } (cwd 기준 상대경로) */
+export function findCss(cwd) {
+  const v4 = []
+  const v3 = []
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) {
+        // 숨김 폴더(.storybook·.template·.cache …)에 진입 CSS 를 두는 레포는 없다
+        if (!PRUNE.has(e.name) && !e.name.startsWith('.')) walk(full)
+      } else if (e.name.endsWith('.css')) {
+        const css = readText(full) ?? ''
+        if (TW4_RE.test(css)) v4.push(path.relative(cwd, full))
+        else if (TW3_RE.test(css)) v3.push(path.relative(cwd, full))
+      }
+    }
+  }
+  walk(cwd)
+  return { v4: v4.sort(), v3: v3.sort() }
+}
+
+export const hasStylesImport = (css) => HAS_STYLES_RE.test(css)
+export const hasFontsImport = (css) => HAS_FONTS_RE.test(css)
+
+/**
+ * `@import 'tailwindcss'` 줄 바로 아래에 TDS import 를 끼운다.
+ * - styles.css 가 없으면 넣는다. 그 파일에 TDS import 가 하나도 없던 새 레포면 fonts.css 도 같이 넣는다.
+ * - styles.css 가 이미 있으면 아무것도 안 넣는다 — 그 레포는 글꼴 로드 방식을 이미 정한 것이다 (dl-ui-v3: next/font).
+ * 바꿀 게 없으면 원문 그대로, tailwind import 줄이 없으면 null.
+ * (소비 쪽 `@source` 줄은 넣지 않는다 — dist/styles.css 가 이미 `@source "./**\/*.js"` 를 가진다. 2026-10-09 실측: 셀렉터 누락 0)
+ */
+export function insertCssImports(css) {
+  const m = TW4_RE.exec(css)
+  if (!m) return null
+  if (HAS_STYLES_RE.test(css)) return css
+  const missing = HAS_FONTS_RE.test(css) ? [CSS_IMPORTS[0]] : CSS_IMPORTS
+  const eol = css.includes('\r\n') ? '\r\n' : '\n'
+  const end = m.index + m[0].length
+  return css.slice(0, end) + eol + missing.join(eol) + css.slice(end)
+}
+
+// ----------------------------------------------------------------------------
+// .mcp.json
+// ----------------------------------------------------------------------------
+
+/** 다른 서버는 보존하고 tds-storybook 만 넣거나 덮어쓴다. JSON 이 깨져 있으면 throw. */
+export function mergeMcpJson(text, url) {
+  const json = text?.trim() ? JSON.parse(text) : {}
+  if (!json.mcpServers || typeof json.mcpServers !== 'object') json.mcpServers = {}
+  json.mcpServers[MCP_SERVER] = { type: 'http', url }
+  return JSON.stringify(json, null, 2) + '\n'
+}
+
+export const mcpUrlOf = (text) => {
+  try {
+    return JSON.parse(text ?? '')?.mcpServers?.[MCP_SERVER]?.url ?? null
+  } catch {
+    return null
+  }
+}
+
+const CODEX_TABLE = `[mcp_servers.${MCP_SERVER}]`
+
+/** .codex/config.toml 관리 블록의 본문 — 원격 MCP 는 `url` 한 줄 */
+export const codexMcpBody = (url) => `${CODEX_TABLE}\nurl = "${url}"`
+
+/** TOML 본문에서 tds-storybook 테이블의 url (테이블 머리 뒤, 다음 테이블 전까지) — 없으면 null. 블록 안이든 밖이든 */
+export function codexMcpUrlOf(text) {
+  let inTable = false
+  for (const raw of (text ?? '').split(/\r?\n/)) {
+    const line = raw.trim()
+    if (line.startsWith('[')) inTable = line === CODEX_TABLE
+    else if (inTable) {
+      const m = /^url\s*=\s*"([^"]*)"/.exec(line)
+      if (m) return m[1]
+    }
+  }
+  return null
+}
+
+/** 관리 블록 밖에 같은 테이블이 있으면 true — 테이블이 두 번이면 TOML 오류라 setup 은 손대지 않는다 */
+export const codexTableOutsideBlock = (text) =>
+  (text ?? '')
+    .replace(blockRe('toml'), '')
+    .split(/\r?\n/)
+    .some((l) => l.trim() === CODEX_TABLE)
+
+// ----------------------------------------------------------------------------
+// 설치된 패키지 · peer
+// ----------------------------------------------------------------------------
+
+export const installedDir = (cwd) => path.join(cwd, 'node_modules', PKG_NAME)
+
+export const readInstalledVersion = (cwd) => {
+  try {
+    return readJson(path.join(installedDir(cwd), 'package.json'))?.version ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * peer 의 설치 버전. cwd/node_modules/<peer> 가 아니라 **설치된 DS 패키지 위치에서** resolve 한다
+ * (pnpm 은 peer 를 가상 스토어에 두어 최상위에 없을 수 있다). 못 찾으면 null.
+ */
+export function resolvePeerVersion(cwd, name) {
+  let base
+  try {
+    base = fs.realpathSync(installedDir(cwd))
+  } catch {
+    return null
+  }
+  const req = createRequire(path.join(base, 'package.json'))
+  let file
+  try {
+    file = req.resolve(`${name}/package.json`)
+  } catch {
+    try {
+      file = req.resolve(name)
+    } catch {
+      return null
+    }
+  }
+  // exports 가 ./package.json 을 막는 패키지는 진입 파일에서 위로 올라가 이름이 맞는 package.json 을 찾는다
+  let dir = path.dirname(file)
+  for (let i = 0; i < 8; i++) {
+    const pkg = readJsonSafe(path.join(dir, 'package.json'))
+    if (pkg?.name === name) return pkg.version ?? null
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+function readJsonSafe(file) {
+  try {
+    return readJson(file)
+  } catch {
+    return null
+  }
+}
+
+export const major = (version) => (version ? Number(String(version).split('.')[0]) : null)
+
+// ----------------------------------------------------------------------------
+// Skill 복사
+// ----------------------------------------------------------------------------
+
+/** 패키지 skills/tds 의 복사 대상 파일 (SKILL_SRC 기준 상대경로) */
+export function skillFiles(src = SKILL_SRC) {
+  const out = []
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) walk(full)
+      else if (!SKILL_SKIP.has(path.relative(src, full))) out.push(path.relative(src, full))
+    }
+  }
+  walk(src)
+  return out.sort()
+}
+
+/** 대상에 빠졌거나 내용이 다른 파일이 하나라도 있으면 true */
+export function skillStale(dest, src = SKILL_SRC) {
+  return skillFiles(src).some(
+    (rel) => readText(path.join(dest, rel)) !== readText(path.join(src, rel)),
+  )
+}
+
+/** 반환: 'unchanged' | 'written' */
+export function copySkill(dest, src = SKILL_SRC) {
+  let written = false
+  for (const rel of skillFiles(src)) {
+    if (writeIfChanged(path.join(dest, rel), readText(path.join(src, rel))) === 'written')
+      written = true
+  }
+  return written ? 'written' : 'unchanged'
+}
+
+// ----------------------------------------------------------------------------
+// 네트워크 (fetch 주입 가능 — 테스트는 가짜 fetch)
+// ----------------------------------------------------------------------------
+
+// VPN 에서 패키지 목록(전 버전) 응답이 3초를 넘긴 적이 있다 (2026-10-09 dl-ui-v3 실측)
+const TIMEOUT_MS = 8000
+
+/**
+ * 레지스트리 인증·최신 버전 (dist-tags 엔드포인트). GitLab npm 엔드포인트는 `Authorization: Bearer <token>` 을 받는다.
+ * 반환 { status: 'ok', latest } | { status: 'auth' | 'notfound' | 'network', detail }
+ */
+export async function checkRegistry(registry, token, fetchImpl = globalThis.fetch, timeoutMs = TIMEOUT_MS) {
+  // 패키지 목록 전체(550KB, VPN 2~3초)가 아니라 dist-tags 만(0.1초). 인증 실패는 똑같이 401 (2026-10-09 실측)
+  const url = `${registry}-/package/${encodeURIComponent(PKG_NAME)}/dist-tags`
+  try {
+    const res = await fetchImpl(url, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (res.status === 401 || res.status === 403)
+      return { status: 'auth', detail: `HTTP ${res.status}` }
+    if (res.status === 404) return { status: 'notfound', detail: 'HTTP 404' }
+    if (!res.ok) return { status: 'network', detail: `HTTP ${res.status}` }
+    const body = await res.json()
+    return { status: 'ok', latest: body?.latest ?? null }
+  } catch (e) {
+    return { status: 'network', detail: e?.message ?? String(e) }
+  }
+}
+
+/**
+ * MCP 서버가 응답하는지 — Streamable HTTP `initialize` 요청 하나로 확인한다.
+ * 공용 사이드카(@storybook/mcp)와 로컬 `storybook dev`(addon-mcp) 둘 다 같은 프로토콜이라 healthz 보다 범용이다.
+ * 응답은 JSON 또는 SSE(text/event-stream) 일 수 있다. 반환 { ok: true, server } | { ok: false, detail }
+ */
+export async function checkMcp(url, fetchImpl = globalThis.fetch, timeoutMs = TIMEOUT_MS) {
+  const body = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2025-06-18',
+      capabilities: {},
+      clientInfo: { name: 't3q-design', version: ownVersion() },
+    },
+  }
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!res.ok) return { ok: false, detail: `HTTP ${res.status}` }
+    const msg = parseMcpResponse(await res.text())
+    if (!msg?.result)
+      return { ok: false, detail: msg?.error?.message ?? 'MCP 응답이 아님 (서버 미배포?)' }
+    const info = msg.result.serverInfo
+    return { ok: true, server: info?.name ? `${info.name} ${info.version ?? ''}`.trim() : null }
+  } catch (e) {
+    return { ok: false, detail: e?.message ?? String(e) }
+  }
+}
+
+/** JSON 본문 또는 SSE(`data: {...}` 줄)에서 JSON-RPC 메시지 하나를 꺼낸다. 아니면 null */
+export function parseMcpResponse(text) {
+  const t = (text ?? '').trim()
+  const candidates = t.startsWith('{')
+    ? [t]
+    : t
+        .split(/\r?\n/)
+        .filter((l) => l.startsWith('data:'))
+        .map((l) => l.slice(5).trim())
+  for (const c of candidates) {
+    try {
+      const j = JSON.parse(c)
+      if (j?.jsonrpc === '2.0') return j
+    } catch {
+      /* 다음 후보 */
+    }
+  }
+  return null
+}