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

package/cli/setup.mjs

@@ -0,0 +1,181 @@
+/**
+ * t3q-design setup — 소비 레포를 AI 작업용으로 준비한다 (README "빠른 시작" 4단계).
+ * 전제: `pnpm add @t3q-ui/design-system` 이 끝나 있다 (이 CLI 가 그 패키지 안에 있으므로).
+ * `.npmrc`·MCP 항목은 `registry`·`mcpUrl` 을 줄 때만 쓴다 — 주소를 패키지에 두지 않는다 (사내 절차: docs/INTERNAL_SETUP.md).
+ * 모든 쓰기는 "달라졌을 때만" — 두 번 돌리면 아무것도 안 바뀐다.
+ */
+import path from 'node:path'
+
+import {
+  CODEX_CONFIG,
+  CODEX_SKILL_DEST,
+  codexMcpBody,
+  codexTableOutsideBlock,
+  copySkill,
+  CSS_IMPORTS,
+  ensureImportLine,
+  ensureNpmrc,
+  findCss,
+  insertCssImports,
+  managedBlock,
+  MCP_SERVER,
+  mergeMcpJson,
+  npmrcLines,
+  ownVersion,
+  PKG_NAME,
+  readInstalledVersion,
+  readText,
+  RULES_FILE,
+  SKILL_DEST,
+  skillStale,
+  upsertManagedBlock,
+  writeIfChanged,
+} from './lib.mjs'
+
+/** @returns {Promise<Array<{ status: 'ok'|'warn'|'fail'|'info', msg: string, fix?: string }>>} */
+export async function setup(cwd, { registry, mcpUrl } = {}) {
+  const results = []
+  const add = (status, msg, fix) => results.push(fix ? { status, msg, fix } : { status, msg })
+  const file = (rel) => path.join(cwd, rel)
+  const version = ownVersion()
+
+  // 0. 설치 확인 (경고만 — 파일은 그래도 써 둔다)
+  const installed = readInstalledVersion(cwd)
+  if (installed) add('ok', `${PKG_NAME} ${installed}`)
+  else add('warn', `${PKG_NAME} 미설치`, `pnpm add ${PKG_NAME}`)
+
+  // 1. .npmrc — --registry 를 줄 때만
+  if (!registry) add('info', '.npmrc 변경 없음 (--registry 를 주면 사내 레지스트리 줄을 기록)')
+  else {
+    const before = readText(file('.npmrc'))
+    const { text, conflict } = ensureNpmrc(before, registry)
+    if (conflict)
+      add(
+        'warn',
+        '.npmrc 에 다른 @t3q-ui:registry 가 있어 손대지 않음',
+        `아래 2줄로 맞춘다:\n${npmrcLines(registry).join('\n')}`,
+      )
+    else if (text === before) add('ok', '.npmrc 이미 최신')
+    else {
+      writeIfChanged(file('.npmrc'), text)
+      add('ok', '.npmrc 갱신 (레지스트리 2줄)')
+    }
+  }
+
+  // 2. CSS — 진입 CSS 가 정확히 1개일 때만 자동 삽입
+  {
+    const { v4, v3 } = findCss(cwd)
+    const paste = `진입 CSS 의 @import 'tailwindcss' 바로 아래에 추가:\n${CSS_IMPORTS.join('\n')}`
+    if (v4.length === 1) {
+      const css = readText(file(v4[0]))
+      const next = insertCssImports(css)
+      if (next === css) add('ok', `CSS ${v4[0]} 이미 최신`)
+      else {
+        writeIfChanged(file(v4[0]), next)
+        const added =
+          next.includes(CSS_IMPORTS[1]) && !css.includes(CSS_IMPORTS[1])
+            ? 'styles.css·fonts.css'
+            : 'styles.css'
+        add('ok', `CSS ${v4[0]} 갱신 (${added} import 추가)`)
+      }
+    } else if (v4.length === 0 && v3.length > 0) {
+      add(
+        'fail',
+        `Tailwind v3 (@tailwind base: ${v3.join(', ')}) — TDS 는 Tailwind v4 가 필요`,
+        'README "Tailwind 설정" 을 따라 v4 로 올린 뒤 다시 setup',
+      )
+    } else if (v4.length === 0) {
+      add('warn', "@import 'tailwindcss' 가 있는 CSS 파일 없음", paste)
+    } else {
+      add('warn', `진입 CSS 후보가 ${v4.length}개 (${v4.join(', ')}) — 자동 수정 안 함`, paste)
+    }
+  }
+
+  // 3. .mcp.json — --mcp-url 을 줄 때만
+  if (!mcpUrl) add('info', '.mcp.json 변경 없음 (--mcp-url 을 주면 MCP 항목을 기록) — Skill reference 로 동작')
+  else {
+    const before = readText(file('.mcp.json'))
+    try {
+      const next = mergeMcpJson(before, mcpUrl)
+      if (next === before) add('ok', `.mcp.json ${MCP_SERVER} 이미 최신`)
+      else {
+        writeIfChanged(file('.mcp.json'), next)
+        add('ok', `.mcp.json ${MCP_SERVER} → ${mcpUrl}`)
+      }
+    } catch {
+      add(
+        'warn',
+        '.mcp.json 파싱 실패 — 손대지 않음',
+        `mcpServers 에 직접 추가:\n${JSON.stringify({ [MCP_SERVER]: { type: 'http', url: mcpUrl } }, null, 2)}`,
+      )
+    }
+  }
+
+  // 4. AGENTS.md 관리 블록
+  {
+    const rules = readText(RULES_FILE)
+    const before = readText(file('AGENTS.md'))
+    const had = managedBlock(before)
+    const next = upsertManagedBlock(before, rules, version)
+    if (next === before) add('ok', 'AGENTS.md TDS 블록 이미 최신')
+    else {
+      writeIfChanged(file('AGENTS.md'), next)
+      add('ok', had ? 'AGENTS.md TDS 블록 갱신' : 'AGENTS.md TDS 블록 추가')
+    }
+  }
+
+  // 5. CLAUDE.md → @AGENTS.md
+  {
+    const before = readText(file('CLAUDE.md'))
+    const next = ensureImportLine(before)
+    if (next === before) add('ok', 'CLAUDE.md @AGENTS.md 이미 있음')
+    else {
+      writeIfChanged(file('CLAUDE.md'), next)
+      add('ok', before == null ? 'CLAUDE.md 생성 (@AGENTS.md)' : 'CLAUDE.md 에 @AGENTS.md 추가')
+    }
+  }
+
+  // 6. Skill 복사
+  {
+    const dest = file(SKILL_DEST)
+    const stale = skillStale(dest)
+    copySkill(dest)
+    add('ok', stale ? `${SKILL_DEST}/ 복사 (/tds)` : `${SKILL_DEST}/ 이미 최신`)
+  }
+
+  // 6b. Codex — 스킬은 .agents/skills/tds, MCP 는 프로젝트 .codex/config.toml 의 관리 블록(# tds:start … # tds:end).
+  // Codex 는 .mcp.json·.claude/skills 를 읽지 않는다(2026-10-27 홀드아웃 13: Codex 9 run 중 7 run 이 MCP 대신 d.ts 만 읽음)
+  {
+    const dest = file(CODEX_SKILL_DEST)
+    const stale = skillStale(dest)
+    copySkill(dest)
+    add('ok', stale ? `${CODEX_SKILL_DEST}/ 복사 (Codex 스킬)` : `${CODEX_SKILL_DEST}/ 이미 최신`)
+    // MCP 주소가 없으면 .codex/config.toml 도 건드리지 않는다
+    const before = readText(file(CODEX_CONFIG))
+    if (!mcpUrl) {
+      add('info', `${CODEX_CONFIG} 변경 없음 (--mcp-url 없음)`)
+    } else if (codexTableOutsideBlock(before)) {
+      add(
+        'warn',
+        `${CODEX_CONFIG} 에 ${MCP_SERVER} 테이블이 이미 있어 손대지 않음`,
+        `그 테이블의 url 이 "${mcpUrl}" 인지 확인`,
+      )
+    } else {
+      const next = upsertManagedBlock(before, codexMcpBody(mcpUrl), version, 'toml')
+      if (next === before) add('ok', `${CODEX_CONFIG} ${MCP_SERVER} 이미 최신`)
+      else {
+        writeIfChanged(file(CODEX_CONFIG), next)
+        add('ok', `${CODEX_CONFIG} ${MCP_SERVER} → ${mcpUrl}`)
+      }
+    }
+  }
+
+  // 7. 안내
+  add('info', 'Claude Code 는 이 프로젝트의 .mcp.json 서버를 첫 실행 때 승인하라고 묻는다 → 승인')
+  add(
+    'info',
+    'Codex 는 규칙(AGENTS.md)·.agents/skills/tds·.codex/config.toml 을 읽는다 — Codex 에서 이 프로젝트를 trust 해야 .codex/config.toml 이 적용된다. Cursor·Copilot 은 규칙·Skill(.claude/skills) 을 그대로 읽고 MCP 는 .cursor/mcp.json, .vscode/mcp.json(키 servers) 에 같은 URL 을 등록',
+  )
+  add('info', '점검: t3q-design doctor')
+  return results
+}

package/cli/t3q-design.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * t3q-design — @t3q-ui/design-system 소비 레포 설치·점검 CLI (로드맵 §7).
+ *   t3q-design setup  [--registry <url>] [--mcp-url <url>] [--cwd <dir>]   AI 작업용 파일을 만들거나 갱신한다
+ *   t3q-design doctor [--cwd <dir>]                     상태를 검사하고 조치를 알려 준다
+ * 이 파일은 출력과 종료 코드만 맡는다. 동작은 setup.mjs / doctor.mjs, 검사는 cli.test.mjs.
+ */
+import path from 'node:path'
+
+import { doctor } from './doctor.mjs'
+import { ownVersion, PKG_NAME } from './lib.mjs'
+import { setup } from './setup.mjs'
+
+const argv = process.argv.slice(2)
+const arg = (name, def) => {
+  const i = argv.indexOf(name)
+  return i >= 0 && argv[i + 1] != null ? argv[i + 1] : def
+}
+/** 끝 슬래시를 보장한다 — 레지스트리 URL 은 `${registry}-/package/…` 로 이어 붙인다 */
+const normRegistry = (r) => (r ? r.replace(/\/?$/, '/') : r)
+const flag = (name) => argv.includes(name)
+const cmd = argv.find((a) => !a.startsWith('-'))
+
+const HELP = `t3q-design — ${PKG_NAME} 설치·점검
+
+사용:
+  t3q-design setup  [--registry <url>] [--mcp-url <url>] [--cwd <dir>]
+  t3q-design doctor [--cwd <dir>]
+
+setup   CSS import · AGENTS.md 블록 · CLAUDE.md · .claude/skills/tds 를 만들거나 갱신. 플래그를 줄 때만 .npmrc(--registry)·.mcp.json·.codex/config.toml(--mcp-url) 도 기록
+doctor  Node · 패키지/peer · CSS · Skill · 규칙을 검사 (실패 시 종료 코드 1). .npmrc 에 @t3q-ui:registry 줄이 있으면 토큰·레지스트리도, .mcp.json 에 항목이 있으면 MCP 도 점검
+
+--registry 사내 npm 레지스트리 주소 (사내 설치 전용 — docs/INTERNAL_SETUP.md)
+--mcp-url  Storybook MCP 주소 (예: 로컬 Storybook http://localhost:6006/mcp). 없으면 MCP 항목을 쓰지 않는다
+--cwd      대상 레포 (기본: 현재 디렉터리)
+`
+
+const ICON = { ok: '✓', warn: '!', fail: '✗', info: '·' }
+
+function print(results) {
+  for (const r of results) {
+    console.log(`${ICON[r.status]} ${r.msg}`)
+    if (r.fix) for (const line of r.fix.split('\n')) console.log(`    → ${line}`)
+  }
+}
+
+async function main() {
+  if (flag('--help') || flag('-h') || !cmd) {
+    console.log(HELP)
+    return flag('--help') || flag('-h') ? 0 : 1
+  }
+  const cwd = path.resolve(arg('--cwd', process.cwd()))
+  if (cmd === 'setup') {
+    console.log(`t3q-design setup (${PKG_NAME} ${ownVersion()}) — ${cwd}\n`)
+    const results = await setup(cwd, { registry: normRegistry(arg('--registry')), mcpUrl: arg('--mcp-url') })
+    print(results)
+    return results.some((r) => r.status === 'fail') ? 1 : 0
+  }
+  if (cmd === 'doctor') {
+    console.log(`t3q-design doctor — ${cwd}\n`)
+    const results = await doctor(cwd)
+    print(results)
+    const fails = results.filter((r) => r.status === 'fail').length
+    console.log(fails ? `\n✗ ${fails}개 실패` : '\n✓ 준비 완료')
+    return fails ? 1 : 0
+  }
+  console.error(`알 수 없는 명령: ${cmd}\n`)
+  console.log(HELP)
+  return 1
+}
+
+main().then(
+  (code) => process.exit(code),
+  (e) => {
+    console.error(`✗ ${e?.stack ?? e}`)
+    process.exit(1)
+  },
+)