8808c672dc
웹 디자인 파이프라인 스킬과 이를 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)
130 lines
5.9 KiB
Markdown
130 lines
5.9 KiB
Markdown
# designpaca 배포 운영 계획
|
|
|
|
이 문서는 designpaca를 git.chanpaca.net(Forgejo)에서 빌드·배포·릴리스하기 위한 전제와 절차를 적는다.
|
|
한 번 읽고 그대로 따라 하면 첫 릴리스까지 갈 수 있어야 한다.
|
|
|
|
## 0. 전제 — 러너 환경
|
|
|
|
CI는 self-hosted **`linux-builder`** 러너(host 모드)에서 돈다. host 모드라 러너 머신에 있는 것만 쓸 수 있다.
|
|
|
|
| 필요 | 확인 | 없을 때 |
|
|
|---|---|---|
|
|
| Node 20 이상 | `node -v` | `fnm install 22 && fnm default 22` 후 러너 재시작 |
|
|
| pnpm 10 | `pnpm -v` | `corepack enable && corepack prepare pnpm@10.5.2 --activate` |
|
|
| git, curl, tar, python3 | `command -v` | 배포판 패키지로 설치 |
|
|
|
|
`build/ci/verify-node.sh`가 매 잡 첫 스텝에서 이걸 검사하고, 없으면 **명확한 메시지로 즉시 실패**시킨다.
|
|
nvm/fnm/volta의 흔한 설치 경로는 자동으로 PATH에 올려본다.
|
|
|
|
> host 러너에는 Node가 없을 수 있으므로 워크플로에서 `uses:` 액션을 쓰지 않는다.
|
|
> 체크아웃도 `run:` 스텝의 git 명령으로 처리한다 (videodownloader 파이프라인과 동일한 패턴).
|
|
|
|
## 1. 저장소
|
|
|
|
```
|
|
git.chanpaca.net/<owner>/designpaca
|
|
```
|
|
|
|
- 소스 공개 여부는 자유. 단 **npm 배포는 npmjs 공개 레지스트리**이므로 코드는 어차피 tarball로 공개된다
|
|
- 기본 브랜치: `main`
|
|
- 태그 규칙: `v<semver>` (예: `v0.1.0`) — 태그 푸시가 릴리스 트리거
|
|
|
|
## 2. 시크릿 등록
|
|
|
|
저장소 → Settings → Actions → Secrets 에 등록한다.
|
|
|
|
| 이름 | 용도 | 발급처 |
|
|
|---|---|---|
|
|
| `NPM_TOKEN` | npmjs 배포 | npmjs.com → Access Tokens → **Automation** 타입 |
|
|
| `FORGEJO_NPM_TOKEN` | 사설 레지스트리 미러 | Forgejo → 설정 → 애플리케이션 → 액세스 토큰 (`write:package` 권한) |
|
|
| `RELEASE_TOKEN` | 릴리스 생성·자산 업로드 | Forgejo 액세스 토큰 (`write:repository`) |
|
|
| `CF_API_TOKEN` | Cloudflare Pages 배포 | Cloudflare → API Tokens → **Edit Cloudflare Workers** 템플릿 |
|
|
| `CF_ACCOUNT_ID` | Cloudflare 계정 식별 | Cloudflare 대시보드 우측 하단 Account ID |
|
|
|
|
변수(Variables)에 선택적으로:
|
|
|
|
| 이름 | 기본값 | 설명 |
|
|
|---|---|---|
|
|
| `FORGEJO_NPM_OWNER` | `yunchan` | 사설 npm 패키지 소유자 |
|
|
|
|
> **시크릿이 없어도 파이프라인은 죽지 않는다.** `publish-npm.sh`는 `FORGEJO_NPM_TOKEN`이 없으면 미러를 건너뛰고,
|
|
> 릴리스 스텝은 `CF_API_TOKEN`이 없으면 페이지 배포를 건너뛴다. 하나씩 붙여가며 굴릴 수 있다.
|
|
|
|
## 3. 릴리스 절차
|
|
|
|
### 3.1 변경 기록
|
|
```bash
|
|
pnpm changeset # 무엇이 바뀌었는지, patch/minor/major 중 무엇인지 기록
|
|
git add .changeset && git commit -m "changeset: <요약>"
|
|
```
|
|
|
|
### 3.2 버전 확정
|
|
```bash
|
|
pnpm version # changeset version + lockfile 갱신
|
|
# packages/*/package.json 과 CHANGELOG.md 가 갱신된다
|
|
git add -A && git commit -m "release: v<새 버전>"
|
|
```
|
|
`designpaca` · `@designpaca/core` · `@designpaca/skill`은 changesets의 **fixed 그룹**이라 항상 같은 버전으로 움직인다.
|
|
스킬 내용과 CLI 버전이 어긋나면 업그레이드 판정(`.designpaca_version` 비교)이 깨지기 때문이다.
|
|
|
|
### 3.3 태그 푸시 = 릴리스 발동
|
|
```bash
|
|
git tag v0.1.0 && git push origin main --tags
|
|
```
|
|
|
|
파이프라인이 순서대로 수행한다:
|
|
1. `verify-node.sh` → 의존성 설치
|
|
2. **태그와 `packages/cli/package.json` 버전 일치 확인** (다르면 즉시 실패)
|
|
3. 스킬 문서 검사 → 타입 검사 → 테스트 → 빌드 → 배포물 점검
|
|
4. `npm publish` (npmjs) → Forgejo 레지스트리 미러. **이미 배포된 버전이면 조용히 건너뛴다**(재실행 안전)
|
|
5. Forgejo **draft 릴리스** 생성 + tarball 첨부
|
|
6. Cloudflare Pages 배포
|
|
|
|
### 3.4 승격
|
|
draft 릴리스를 확인하고 수동으로 **Publish**한다. draft는 익명에게 보이지 않으므로 QA 시간을 벌 수 있다.
|
|
|
|
### 3.5 리허설
|
|
태그 없이 돌려볼 수 있다. Actions → release → **Run workflow**.
|
|
`ci-rehearsal` prerelease 릴리스로 전 과정을 검증하되 **npm 배포는 건너뛴다**(`DO_PUBLISH=0`).
|
|
|
|
## 4. 사용자 설치 경로
|
|
|
|
```bash
|
|
npx designpaca # 온보딩 TUI
|
|
npx designpaca install -t claude-code,codex -s user -y
|
|
```
|
|
|
|
사설 레지스트리에서 직접 받으려면:
|
|
```bash
|
|
npx --registry=https://git.chanpaca.net/api/packages/<owner>/npm/ designpaca
|
|
```
|
|
|
|
## 5. 소개 페이지
|
|
|
|
- 배포 대상: Cloudflare Pages 프로젝트 **`designpaca`**
|
|
- 도메인: `designpaca.chanpaca.net` (Cloudflare DNS에 CNAME → Pages)
|
|
- 최초 1회만 수동: Cloudflare 대시보드에서 Pages 프로젝트 생성(빈 프로젝트) → 커스텀 도메인 연결.
|
|
이후에는 릴리스 워크플로의 `wrangler pages deploy`가 알아서 올린다
|
|
|
|
## 6. 장애 대응
|
|
|
|
| 증상 | 원인 | 조치 |
|
|
|---|---|---|
|
|
| `Node 를 찾을 수 없다` | host 러너에 Node 미설치 | 러너 머신에 fnm으로 Node 22 설치 후 러너 재시작 |
|
|
| `태그와 package.json 이 다르다` | `pnpm version` 없이 태그를 밀었다 | 태그 삭제 → 3.2부터 다시 |
|
|
| npm publish 403 | 토큰 만료 / 이름 선점 | `NPM_TOKEN` 재발급, `npm view designpaca` 로 소유 확인 |
|
|
| Forgejo 미러 401 | 토큰에 `write:package` 없음 | 토큰 권한 재발급 |
|
|
| 릴리스 자산 업로드 실패 | `RELEASE_TOKEN` 권한 부족 | `write:repository` 부여 |
|
|
| Pages 배포 스킵 | `CF_API_TOKEN` 미등록 | 시크릿 등록 (없어도 나머지는 성공한다) |
|
|
|
|
## 7. 롤백
|
|
|
|
npm은 배포 취소가 사실상 불가능하다(72시간 이내 unpublish만 가능, 같은 버전 재사용 금지).
|
|
따라서 **되돌리기가 아니라 앞으로 감는다**:
|
|
|
|
```bash
|
|
# 문제 버전을 latest 에서 내린다
|
|
npm dist-tag add designpaca@<직전 정상 버전> latest
|
|
# 수정 후 새 패치 릴리스
|
|
```
|
|
사용자 쪽 복구는 `npx designpaca@<정상버전> update --force`.
|