designpaca 초기 구현 — 스킬 · 설치 CLI · 배포 파이프라인

웹 디자인 파이프라인 스킬과 이를 5개 에이전트에 설치하는 CLI 를 담은 모노레포. 스킬 (packages/skill) - SKILL.md 261줄 + 참조 문서 16개 3,349줄. progressive disclosure 로 본문은 절차와 인덱스만, 지식은 references/ 로 분리 - 0~6단계 파이프라인. 규모에 따라 전체·연장·국소 세 경로로 분기 - 하드 게이트 12개는 grep·카운트로 검증 가능한 것만. 취향 판단은 제외 - 미학 프리셋 5종, AI 슬롭 지문 목록, 한글 조판 규칙, SVG 필터·three.js·인터랙티브 모션·HTML-in-Canvas 실전 지침 설치 CLI (packages/cli, packages/core) - npx designpaca 온보딩 TUI. Claude Code · Codex · Cursor · Windsurf · AGENTS.md - 매니페스트에 설치 시점 해시를 기록해 사용자가 고친 파일은 update 가 건너뛴다 - 타깃별로 본문의 references/ 경로를 실제 설치 위치로 재작성 - AGENTS.md 는 항상 로드되므로 본문 대신 303자 포인터만 주입 - Windsurf 는 12,000자 상한 초과 시 설치를 차단 배포 (build/ci, .forgejo/workflows) - 태그 v* → 검사·테스트·빌드 → npmjs 배포 + Forgejo 레지스트리 미러 → draft 릴리스 → Cloudflare Pages. 재실행 멱등 근거 (research/) - 약 250개 웹 소스 조사 결과와 도그푸딩 검증 2건. 스킬의 모든 수치는 여기서 나온다 테스트 22개 통과 (core 16 · cli 6)
2026-08-20 10:48:00 +09:00 · 2026-08-20 10:48:00 +09:00 · 8808c672dc
commit 8808c672dc
135 changed files with 38838 additions and 0 deletions
--- a/build/ci/lint-skill.mjs
+++ b/build/ci/lint-skill.mjs
@ -0,0 +1,80 @@
+// 스킬 문서의 최소 규약을 검사한다. CI 와 `pnpm test` 가 함께 쓴다.
+// - SKILL.md 존재와 프론트매터 필수 필드
+// - description 길이(트리거 정확도에 직접 영향)
+// - references 링크가 실제 파일을 가리키는지
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = path.resolve(process.argv[2] ?? ".");
+const errors = [];
+const warnings = [];
+
+const skillPath = path.join(root, "SKILL.md");
+let md;
+try {
+  md = await fs.readFile(skillPath, "utf8");
+} catch {
+  console.error(`SKILL.md 를 찾을 수 없다: ${skillPath}`);
+  process.exit(1);
+}
+
+const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+if (!fmMatch) {
+  errors.push("프론트매터(---)가 없다");
+} else {
+  const fm = Object.fromEntries(
+    fmMatch[1]
+      .split(/\r?\n/)
+      .map((l) => /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(l))
+      .filter(Boolean)
+      .map((m) => [m[1], m[2].replace(/^["']|["']$/g, "")]),
+  );
+  if (fm.name !== "designpaca") errors.push(`name 이 designpaca 가 아니다: ${fm.name}`);
+  if (!fm.description) errors.push("description 이 없다");
+  else {
+    const len = fm.description.length;
+    if (len < 80) warnings.push(`description 이 짧다(${len}자) — 트리거 정확도가 떨어진다`);
+    if (len > 700) warnings.push(`description 이 길다(${len}자) — 요약해라`);
+  }
+}
+
+// 본문이 참조하는 파일이 실제로 있는지 확인한다 (references/xxx.md 형태)
+const refs = [...md.matchAll(/references\/[A-Za-z0-9._/-]+\.md/g)].map((m) => m[0]);
+for (const rel of new Set(refs)) {
+  try {
+    await fs.access(path.join(root, rel));
+  } catch {
+    errors.push(`본문이 가리키는 참조 문서가 없다: ${rel}`);
+  }
+}
+
+// 참조 문서가 본문 어디에서도 언급되지 않으면 죽은 문서다
+async function walk(dir, base = dir) {
+  const out = [];
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(full, base)));
+    else out.push(path.relative(base, full).split(path.sep).join("/"));
+  }
+  return out;
+}
+const refDir = path.join(root, "references");
+for (const f of await walk(refDir, root)) {
+  if (!f.endsWith(".md")) continue;
+  const rel = f.split(path.sep).join("/");
+  if (!md.includes(rel)) warnings.push(`본문에서 참조되지 않는 문서: ${rel}`);
+}
+
+for (const w of warnings) console.warn(`  경고: ${w}`);
+if (errors.length > 0) {
+  for (const e of errors) console.error(`  오류: ${e}`);
+  console.error(`\n스킬 검사 실패 — 오류 ${errors.length}건`);
+  process.exit(1);
+}
+console.log(`스킬 검사 통과 (경고 ${warnings.length}건)`);
--- a/build/ci/publish-npm.sh
+++ b/build/ci/publish-npm.sh
@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# designpaca 패키지를 npmjs 에 배포하고 Forgejo 사설 레지스트리에 미러링한다.
+#
+# 필요 환경:
+#   NPM_TOKEN          npmjs 자동화 토큰 (필수)
+#   FORGEJO_NPM_TOKEN  Forgejo 개인 액세스 토큰 (선택 — 없으면 미러를 건너뛴다)
+#   FORGEJO_NPM_OWNER  Forgejo 패키지 소유자 (기본: yunchan)
+#   GITHUB_SERVER_URL  Forgejo 주소 (Actions 가 준다)
+#
+# 이미 배포된 버전이면 조용히 건너뛴다 — 워크플로 재실행이 실패로 끝나지 않게.
+set -euo pipefail
+
+PKG_DIR="${1:-packages/cli}"
+cd "$PKG_DIR"
+
+name="$(node -p 'require("./package.json").name')"
+version="$(node -p 'require("./package.json").version')"
+echo "배포 대상: ${name}@${version}"
+
+published() { # <registry-url>
+  npm view "${name}@${version}" version --registry "$1" >/dev/null 2>&1
+}
+
+# ── 1) npmjs ──
+if [ -z "${NPM_TOKEN:-}" ]; then
+  echo "NPM_TOKEN 이 없다 — npmjs 배포를 건너뛴다" >&2
+else
+  npmrc="$(mktemp)"
+  echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "$npmrc"
+  export NPM_CONFIG_USERCONFIG="$npmrc"
+
+  if published "https://registry.npmjs.org/"; then
+    echo "npmjs: ${version} 은 이미 배포돼 있다 — 건너뛴다"
+  else
+    npm publish --access public --registry "https://registry.npmjs.org/" --provenance=false
+    echo "npmjs 배포 완료: ${name}@${version}"
+  fi
+  rm -f "$npmrc"
+  unset NPM_CONFIG_USERCONFIG
+fi
+
+# ── 2) Forgejo 미러 ──
+if [ -z "${FORGEJO_NPM_TOKEN:-}" ]; then
+  echo "FORGEJO_NPM_TOKEN 이 없다 — 사설 레지스트리 미러를 건너뛴다"
+  exit 0
+fi
+
+owner="${FORGEJO_NPM_OWNER:-yunchan}"
+server="${GITHUB_SERVER_URL:-https://git.chanpaca.net}"
+host="${server#*://}"; host="${host%/}"
+registry="${server%/}/api/packages/${owner}/npm/"
+
+npmrc="$(mktemp)"
+{
+  echo "registry=${registry}"
+  # 스킴을 뺀 형태로 적어야 Forgejo 가 인증을 인식한다
+  echo "//${host}/api/packages/${owner}/npm/:_authToken=${FORGEJO_NPM_TOKEN}"
+} > "$npmrc"
+export NPM_CONFIG_USERCONFIG="$npmrc"
+
+if published "$registry"; then
+  echo "Forgejo: ${version} 은 이미 미러돼 있다 — 건너뛴다"
+else
+  npm publish --registry "$registry"
+  echo "Forgejo 미러 완료: ${registry}"
+fi
+rm -f "$npmrc"
--- a/build/ci/upload-release-asset.sh
+++ b/build/ci/upload-release-asset.sh
@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Forgejo 릴리스(draft)에 산출물을 업로드한다. 릴리스가 없으면 만들고, 동명 자산은 교체한다(재실행 멱등).
+# 사용: build/ci/upload-release-asset.sh <릴리스태그> <파일...>
+# 필요 환경: RELEASE_TOKEN + (Actions 기본 제공) GITHUB_SERVER_URL, GITHUB_REPOSITORY
+#            RELEASE_REPO 를 주면 해당 저장소로 업로드(공개 배포 저장소용), 없으면 현재 저장소
+#            RELEASE_PRERELEASE=true 면 prerelease 로 생성(리허설용)
+set -euo pipefail
+[ $# -ge 2 ] || { echo "사용법: $0 <태그> <파일...>" >&2; exit 2; }
+[ -n "${RELEASE_TOKEN:-}" ] || { echo "RELEASE_TOKEN 환경변수가 없습니다" >&2; exit 2; }
+tag="$1"; shift
+api="${GITHUB_SERVER_URL%/}/api/v1/repos/${RELEASE_REPO:-$GITHUB_REPOSITORY}"
+auth="Authorization: token ${RELEASE_TOKEN}"
+
+# draft 릴리스는 tags/<tag> 단건 조회에 안 잡힐 수 있어 목록에서 tag_name 으로 찾는다
+# tr -d '\r': Windows Git Bash 에서 python 출력이 CRLF 로 나와 id 가 오염되는 것 방지
+find_release() {
+  curl -sf -H "$auth" "$api/releases?limit=50" | python3 -c '
+import json, sys
+tag = sys.argv[1]
+for r in json.load(sys.stdin):
+    if r.get("tag_name") == tag:
+        print(r["id"]); break' "$tag" | tr -d '\r'
+}
+
+rid="$(find_release || true)"
+if [ -z "$rid" ]; then
+  body=$(printf '{"tag_name":"%s","name":"%s","draft":true,"prerelease":%s}' \
+         "$tag" "$tag" "${RELEASE_PRERELEASE:-false}")
+  rid=$(curl -s -X POST -H "$auth" -H 'Content-Type: application/json' -d "$body" "$api/releases" \
+        | python3 -c 'import json,sys
+d = json.load(sys.stdin)
+print(d["id"] if isinstance(d, dict) and "id" in d else "")' | tr -d '\r' || true)
+  [ -n "$rid" ] || rid="$(find_release || true)"   # 병렬 잡 동시 생성 경합 대비
+fi
+[ -n "$rid" ] || { echo "릴리스 확보 실패: $tag" >&2; exit 1; }
+echo "릴리스 #$rid ($tag)"
+
+for f in "$@"; do
+  name=$(basename "$f")
+  # 재실행 멱등성: 동명 자산 제거 후 업로드
+  curl -sf -H "$auth" "$api/releases/$rid/assets" | python3 -c '
+import json, sys
+for a in json.load(sys.stdin):
+    if a.get("name") == sys.argv[1]:
+        print(a["id"])' "$name" | tr -d '\r' | while read -r aid; do
+    [ -n "$aid" ] && curl -sf -X DELETE -H "$auth" "$api/releases/$rid/assets/$aid" || true
+  done
+  resp=$(mktemp)
+  code=$(curl -s -o "$resp" -w '%{http_code}' -X POST -H "$auth" \
+         -F "attachment=@$f" "$api/releases/$rid/assets?name=$name")
+  if [ "$code" != 201 ]; then
+    echo "업로드 실패($code): $name" >&2; cat "$resp" >&2; rm -f "$resp"; exit 1
+  fi
+  rm -f "$resp"
+  echo "업로드 완료: $name ($(du -h "$f" | cut -f1))"
+done
--- a/build/ci/verify-node.sh
+++ b/build/ci/verify-node.sh
@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# host 모드 러너에는 Node 가 없을 수 있다. 여기서 명확히 실패시켜 CI 로그를 읽을 수 있게 한다.
+# 필요하면 러너에 nvm/fnm 으로 설치된 Node 를 PATH 에 올려준다.
+set -euo pipefail
+
+MIN_MAJOR=20
+
+add_path() { echo "$1" >> "${GITHUB_PATH:-/dev/null}"; export PATH="$1:$PATH"; }
+
+if ! command -v node >/dev/null 2>&1; then
+  # 러너에 흔히 있는 위치를 훑는다
+  for cand in "$HOME/.nvm/versions/node"/*/bin "$HOME/.local/share/fnm/node-versions"/*/installation/bin "$HOME/.volta/bin"; do
+    [ -d "$cand" ] && add_path "$cand" && break
+  done
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  cat >&2 <<'MSG'
+Node 를 찾을 수 없다.
+
+이 워크플로는 self-hosted host 러너에서 돈다. 러너 머신에 Node 20 이상을 설치하고
+러너 사용자의 PATH 에 올려라. 예: fnm install 22 && fnm default 22
+MSG
+  exit 1
+fi
+
+major="$(node -p 'process.versions.node.split(".")[0]')"
+if [ "$major" -lt "$MIN_MAJOR" ]; then
+  echo "Node $MIN_MAJOR 이상이 필요하다 (현재 $(node -v))" >&2
+  exit 1
+fi
+
+# pnpm 은 corepack 으로 확보한다 — 러너에 전역 설치를 요구하지 않는다
+if ! command -v pnpm >/dev/null 2>&1; then
+  corepack enable >/dev/null 2>&1 || true
+  corepack prepare pnpm@10.5.2 --activate >/dev/null 2>&1 || true
+fi
+if ! command -v pnpm >/dev/null 2>&1; then
+  echo "pnpm 을 확보하지 못했다. corepack 이 막혀 있으면 npm i -g pnpm@10.5.2 로 설치해라" >&2
+  exit 1
+fi
+
+echo "node $(node -v) / pnpm $(pnpm -v) / npm $(npm -v)"