.wia 완전 가이드

1. .wia가 뭔가요?

.wia는 파일 확장자입니다. .md(마크다운)처럼요.

한 줄로 설명하면:

마크다운 파일(.md)은 읽기만 됩니다. 코드 블록이 있어도 그냥 텍스트로 보여줄 뿐이죠.

.wia 파일은 그 코드 블록을 진짜 실행할 수 있습니다. 그리고 결과가 맞는지 자동 검증합니다.

2. 왜 필요한가요?

Before: 기존 방식

1. 위키(Confluence)에서 절차 문서 열기
2. 명령어를 눈으로 읽기
3. 터미널에 복사 → 붙여넣기
4. 결과를 눈으로 확인
5. 감사(SOC2)용 스크린샷 촬영

새벽 3시에 졸리면? → 서버 잘못 치면? → 대참사.

After: .wia 방식

1. .wia 파일 열기
2. Run All 클릭
3. 자동 실행 + 자동 검증 + 자동 기록

끝. 복사→붙여넣기 없음. 실수 없음. 감사 증거 자동 생성.

3. 파일 구조

.wia 파일은 두 부분으로 나뉩니다:

---
wia: "1"
title: 서버 점검
agent: soomy
inputs:
  server_ip: { type: string, default: "10.0.1.100" }
---

# 서버 점검

여기는 일반 마크다운 텍스트입니다.
**굵게**, *기울임*, `코드` 다 됩니다.

```sh run
echo "Hello from .wia!"
```

① Front-matter (머리말)

---와 --- 사이의 YAML 영역. 문서의 메타데이터입니다.

② Body (본문)

일반 마크다운 + 실행 가능한 코드 블록.

4. 블록 타입 6가지

① sh run — 셸 명령 실행

```sh run
df -h /
```

Run 버튼 클릭 → 서버에서 명령 실행 → 결과 표시.

② verify expect=0 — 자동 검증

```verify expect=0
systemctl is-active nginx
```

exit code가 0이면 ✓ PASS, 아니면 ✗ FAIL.

다양한 expect 표현식:

③ ai — AI에게 질문

```ai model=gpt-4o
위 명령의 출력을 분석해서 개선점을 알려줘.
```

이전 블록의 출력이 {{$prev}}로 자동 전달됩니다.

④ sql run on= — SQL 실행

```sql run on=prod-db
SELECT count(*) FROM users WHERE active = 1;
```

⑤ python run / node run

```python run
import json
print(json.dumps({"status": "ok"}, indent=2))
```

⑥ 일반 코드 블록 (display)

```sh
# 이건 실행 안 됨. 그냥 보여주기용.
echo "display only"
```

5. 변수와 입력

사용자 입력 변수

front-matter에서 정의, 본문에서 {{변수명}}으로 사용:

---
wia: "1"
title: 서버 점검
inputs:
  server_ip: { type: string, default: "10.0.1.100" }
  port: { type: number, default: 8080 }
  env: { type: enum, of: [dev, staging, prod] }
  api_key: { type: secret }
  debug: { type: boolean, default: false }
---

```sh run
curl http://{{server_ip}}:{{port}}/health
```

WiaDocRunner가 입력 필드를 자동 생성합니다:

• string → 텍스트 입력
• number → 숫자 입력
• enum → 드롭다운 선택
• secret → 비밀번호 입력 (마스킹, AI 전송 시 *** 처리)
• boolean → 체크박스

특수 변수

6. 안전 장치

7. 실행하는 방법

방법 1: WIA SOOM 앱에서 (풀 파워)

1. SFTP로 서버 접속
2. .wia 파일 더블클릭
3. WiaDocRunner가 열림
4. Run All 클릭 → 전체 실행 + 검증

방법 2: 코드 에디터에서

1. 사이드바 → 편집기
2. .wia 파일 열기
3. 하단에 WiaDocRunner 자동 표시

방법 3: 웹 뷰어에서 (읽기만)

1. wia.wiasoom.com/view 접속
2. .wia 파일 드래그 앤 드롭
3. 내용 확인 (실행은 WIA SOOM 필요)

방법 4: VS Code에서 (읽기만)

.wia 파일을 VS Code로 열면 마크다운으로 보입니다. 실행은 안 되지만 읽기는 됩니다.

8. 만드는 방법

방법 1: 직접 작성

아무 텍스트 에디터에서 파일 이름을 xxx.wia로 저장하면 됩니다.

방법 2: .md → .wia 변환

wia.wiasoom.com/convert에서 기존 .md 파일을 업로드하면 자동 변환됩니다.

방법 3: 앱에서 자동 생성

• RunbookPanel → "Create New .wia" 위저드
• SFTP 우클릭 → "New .wia Runbook"
• 터미널에서 명령 실행 후 → "런북으로 저장" 배너
• Soomy에게 "런북 만들어줘" → AI 자동 생성

방법 4: 45+ 포맷에서 변환

.sh, .py, .sql, .yml, .json, .env, .tf, .ipynb 등 45+ 포맷이 .wia로 변환 가능합니다.

방법 5: 갤러리에서 선택

WIA SOOM 런북 패널에서 111개 갤러리 템플릿 중 원하는 것을 선택할 수 있습니다.

• 18개 카테고리: Server Setup, Web Server, Database, Docker, Kubernetes, Monitoring, Security, CI/CD, Cloud, Communication, ROS/Robot, Application, Incident Response, Networking, Disaster Recovery, Performance, SRE Process, Compliance
• 클릭만으로 즉시 에디터에 로드됩니다.

방법 6: 파일 Import

파일 Import 다이얼로그로 로컬 JSON/Markdown/.wia 파일을 직접 불러올 수 있습니다.

9. 실전 예제 5개

예제 1: 서버 점검

---
wia: "1"
title: 서버 건강 점검
agent: soomy
---

# 디스크 확인
```sh run
df -h /
```

# 메모리 확인
```sh run
free -h
```

# 서비스 상태 확인
```verify expect=0
pm2 pid my-api > /dev/null 2>&1
```

# AI 분석
```ai
위 결과를 분석해서 문제가 있으면 알려줘.
```

예제 2: SSL 인증서 갱신

---
wia: "1"
title: SSL 인증서 갱신
inputs:
  domain: { type: string, default: "example.com" }
---

# 만료일 확인
```sh run
echo | openssl s_client -connect {{domain}}:443 2>/dev/null | openssl x509 -noout -dates
```

# 갱신 (승인 필요)
```sh run approve
certbot renew --cert-name {{domain}}
```

# 갱신 확인
```verify expect=contains:OK
curl -sI https://{{domain}} | head -1
```

예제 3: 로봇 진단

---
wia: "1"
title: ROS 2 로봇 진단
agent: soomy
---

# 노드 목록
```sh run
ros2 node list
```

# 네비게이션 노드 확인
```verify expect=0
ros2 node info /navigation_node
```

# AI 진단
```ai model=gpt-4o
위 로봇 상태를 분석하고 정비 필요 사항을 알려줘.
```

예제 4: 장애 대응

---
wia: "1"
title: 장애 대응
inputs:
  service: { type: enum, of: [my-api, my-worker, my-frontend] }
---

# 상태 확인
```sh run
pm2 describe {{service}} | head -15
```

# 최근 로그
```sh run
pm2 logs {{service}} --nostream --lines 20
```

# 재시작 (승인 필요)
```sh run approve
pm2 restart {{service}}
```

# 재시작 확인
```verify expect=0
sleep 3 && pm2 pid {{service}} > /dev/null 2>&1
```

예제 5: 보안 감사

---
wia: "1"
title: 보안 감사
---

# SSH 루트 로그인 차단 확인
```verify expect=contains:no
grep "^PermitRootLogin" /etc/ssh/sshd_config
```

# 열린 포트 스캔
```sh run
ss -tlnp | grep LISTEN
```

# 실패한 로그인 시도
```sh run
journalctl -u sshd --since "1 hour ago" | grep "Failed" | wc -l
```

# AI 보안 분석
```ai
위 감사 결과를 분석하고 보안 권고사항을 제시해줘.
```

10. 다른 포맷과 비교

11. 자주 묻는 질문

Q: .md 파일을 .wia로 바꿔도 되나요?

네, 확장자만 바꾸면 됩니다. 하지만 바꿀 필요는 없습니다. 실행이 필요한 문서만 .wia로 새로 만드세요. 일반 문서는 .md 그대로.

Q: WIA SOOM 없이도 .wia를 볼 수 있나요?

네. VS Code에서 마크다운으로 보이고, 웹 뷰어에서도 볼 수 있습니다. 단, 실행은 WIA SOOM이 필요합니다.

Q: .wia 파일을 열면 자동으로 실행되나요?

절대 아닙니다. 열기만 해서는 아무것도 실행 안 됩니다. 반드시 Run 버튼을 클릭해야 합니다. 이건 보안 원칙입니다.

Q: 254개 언어를 지원한다는 게 무슨 뜻인가요?

WIA SOOM 앱의 UI가 254개 언어로 번역되어 있습니다. .wia 파일 내용 자체는 어떤 언어로든 작성 가능합니다.

Q: 무료인가요?

.wia 포맷 사양은 오픈 소스(Apache-2.0 / CC-BY-4.0)입니다. WIA SOOM 앱은 무료 다운로드이며, 고급 기능은 유료 플랜입니다.

Q: ROS 2와 무슨 관계인가요?

로봇도 결국 리눅스입니다. .wia로 ROS 2 명령을 실행하고 로봇 상태를 검증할 수 있습니다. 로봇 플릿 운영의 표준 런북 포맷을 목표로 합니다.