test-msw-vfs-cli

MSW 에셋 CLI 래퍼 —

@choigawoon/msw-vfs-cli

.map

.ui

.gamelogic

.model

world.yaml

에 걸친 읽기·탐색·편집·변환을

@choigawoon/msw-vfs-cli@0.5.3

단일 CLI 로 처리한다.

npx

로 호출하므로 로컬 설치 불필요 — npm 이 첫 호출 시 캐싱.

버전 핀 — 한 곳에서 관리

Pin:
```
@choigawoon/msw-vfs-cli@0.5.3
```
Sources of truth (셋 다 일치해야 함):
1. 이 파일 상단의 버전 표기
2. ```
scripts/msw-vfs.js
```
  의
```
PKG
```
  상수
3. ```
scripts/msw-vfs-batch.js
```
  의
```
PKG
```
  상수
동일한 CLI 버전이 뷰어(
```
packages/viewer/src/lib/vfs.ts
```
의
```
REQUIRED_CLI_VERSION
```
) 에서도 요구된다. 스킬·CLI·뷰어 셋 모두 같은 마이너(
```
^0.5.0
```
) 안에서 움직여야
```
read-entity
```
/
```
edit-component
```
같은 L2 호출과 데몬 session recorder 가 맞물린다.

AI 호출 가시성 —

--ai

플래그

단발 래퍼

scripts/msw-vfs.js

는 매 호출에 --ai
를 자동으로 붙인다 (CLI 0.5.3+ 의 client-identity 플래그). 의미:

데몬이 살아 있으면 호출이
```
~/.msw-vfs/sessions/s_<ts>_<id>.jsonl
```
에 자동 기록됨.
동일 데몬에 붙은 뷰어 (
```
@choigawoon/msw-vfs-viewer
```
) 의 Activity 패널에 실시간으로 뜸 (client 뱃지 =
```
ai
```
).
데몬이 없으면 로컬 fallback — 동작은 그대로, 기록만 안 됨.

배치 래퍼 (
scripts/msw-vfs-batch.js
) 는 예외:

serve

서브커맨드가 in-process 파이프라 데몬

/rpc

를 거치지 않는다. 따라서 batch 호출은 recorder 가시성이 없다 — 기록이 필요하면 단발 래퍼를 쓴다. (동시에 캐시 효과는 단발도 데몬 위에서 동등하게 누림.)

실행 방식 — 에이전트 위임

이 스킬이 트리거되면 직접 CLI 를 실행하지 말고,

msw-blob-vfs-reader

에이전트에 위임한다.

Agent(
  subagent_type="msw-devtools:msw-blob-vfs-reader",
  description="맵/UI 분석",
  prompt="<사용자 요청 + 대상 파일 경로를 포함한 구체적 지시>"
)

이유:

.map

.ui

출력은 대량이며 메인 컨텍스트를 오염시킨다. 에이전트가 sonnet 모델로 분석 후 요약만 돌려주므로 컨텍스트 효율이 높다.

예외 — 에이전트 위임 없이 직접 실행하는 경우:

사용자가 명시적으로 "여기서 직접 해줘"라고 요청한 경우
분석 결과를 바탕으로 즉시 편집 작업이 이어지는 경우 (편집 컨텍스트가 필요)

기본 호출 — 단발 (1 쿼리)

bash

node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs.js <file> <subcmd> [args...]

래퍼가
```
npx -y @choigawoon/msw-vfs-cli@0.5.3
```
로 실행 — 별도 설치 불필요.
stdio 는 pass-through. 출력은 CLI 가 직접 쓰는 포맷(text + JSON 혼합).
```
<file>
```
은
```
.map
```
/
```
.ui
```
/
```
.gamelogic
```
/
```
.model
```
중 하나. YAML/world 모드는
```
--type
```
선행 필요.

배치 호출 — N 쿼리 (serve)

동일 파일에 여러 쿼리를 던질 때

serve

파이프를 쓰면 Node 콜드 스타트 + JSON 파싱 비용이 한 번으로 상각된다.

bash

# 파일로부터
node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs-batch.js queries.jsonl

# stdin
cat queries.jsonl | node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs-batch.js

요청 포맷 (newline-JSON, 한 줄 1 쿼리)

json

{"id":"a","argv":["/abs/map01.map","summary"]}
{"id":"b","argv":["/abs/map01.map","read-entity","/maps/map01/Hero"]}
{"id":"c","argv":["/abs/map01.map","grep-entities","BossRush"]}

argv[0]

은 파일 경로. 나머지는 CLI 서브커맨드 + 플래그. 응답은

{id,stdout,stderr,code}

형태의 newline-JSON.

⚠️ 명령 선택의 선결 조건 — entry 타입 먼저 확인

모든 명령이 모든 파일에 동작하지 않는다. 명령을 고르기 전에 먼저 파일 확장자를 보고 분기한다.

Entry	쓸 수 있는 명령군	트리/엔티티 명령 가능?
`.map` / `.ui` / `.gamelogic`	L1 VFS + L2 Entity + YAML export/import	✅
`.model`	`.model` 전용 서브셋: `info` / `list` / `get` / `set` / `remove` / `summary` / `validate`	❌ — 트리 없음
`world.yaml`	`--type world` + `build-world` 만	❌

.model

은 단일 템플릿 (메타 +

Values[]

행 테이블) — 자식 엔티티 트리가 없고 런타임에 소비되어 엔티티 1 개를 만든다. 그래서 트리 가정 명령 (

ls

tree

read-entity

list-entities

edit-entity

add-component

…) 은 모두 거부된다:

$ msw-vfs DefaultPlayer.model list-entities
msw-vfs: 'list-entities' is not a .model command —
         .model has no children; a .model produces one entity at runtime.

.model

작업 라우팅 치트시트

의도	`.map` / `.ui` 에서라면	`.model` 에서는
메타데이터 / 컴포넌트 카운트	`summary` / `read-entity`	`info` 또는 `summary`
들어있는 값들 나열	(개념상 다름)	`list`
값 하나 읽기	`read-entity` 하위	`get <name> [--target-type T]`
값 변경	`edit-component`	`set <name> <json> [--target-type T]`
값 제거	—	`remove <name>`
모델이 만들 엔티티 트리를 펼쳐 보고 싶음	(해당 없음)	`.map` / `.ui` 에 `spawn-model` 으로 펼친 뒤 그 파일에서 트리 명령

흔한 환각 — 존재하지 않는 명령들

다음 이름들은 그럴듯하지만 CLI 에 존재하지 않는다. 호출 전에 의심하라:

❌
```
list-components
```
— 어디에도 없음. "엔티티가 가진 컴포넌트들"을 보려면
```
.map
```
/
```
.ui
```
에서 read-entity <path> --deep
(전체 컴포넌트 묶음 반환).
```
.model
```
에서는 info
의 JSON 안
```
Components
```
배열을 본다.
❌
```
list-entities
```
on
```
.model
```
— 위 규칙대로 거부됨.
❌
```
edit-component
```
on
```
.model
```
—
```
.model
```
의 컴포넌트 값은
```
set <name>
```
으로 편집한다 (
```
--target-type
```
으로 어느 컴포넌트의 값인지 한정).
❌
```
summary
```
가 빠진 명령 —
```
.model
```
에서도
```
summary
```
는 동작한다 (component_counts 포함).

확신이 안 서면 반드시

msw-vfs --help

를 먼저 본다. 도움말이 entity-tree 섹션과

.model

섹션을 분리해 보여준다.

자세한 호환성 표는 docs/vfs-commands.md 최상단 "명령 ↔ entry 타입 호환성" 섹션.

두 레이어 — L1(VFS) vs L2(Entity) — entity-tree entry 전용

위 표대로
.model
/
world.yaml
에는 적용되지 않는다.
.map
/
.ui
/
.gamelogic
안에서 같은 데이터를 두 각도로 노출한다는 의미.

선택 기준:

탐색·검색·grep → L1 (
```
ls
```
/
```
tree
```
/
```
glob
```
/
```
grep
```
/
```
read
```
/
```
stat
```
/
```
summary
```
)

엔티티 단위 읽기·편집·CRUD → L2 (

read-entity

list-entities

find-entities

grep-entities

edit-entity

edit-component

add-entity

remove-entity

/ …)

세부 명령 카탈로그는 upstream

COMMANDS.md

또는

msw-vfs --help

원칙

.map
/
.ui
를 Read 툴로 직접 열지 않는다. 단일 거대 JSON 이라 컨텍스트 초과. 반드시 CLI 를 경유.
탐색은 lazy 하게 —
```
ls /
```
부터 한 층씩.
```
tree --depth 3
```
부터 치지 않는다.
편집은 L2 기본 — 엔티티 메타는
```
edit-entity
```
, 컴포넌트 값은
```
edit-component
```
. L1
```
edit <path>.json
```
은 같은
```
@type
```
컴포넌트가 한 엔티티에 2 개 이상인 모호성 탈출구일 때만.
편집 전에 반드시
read-entity
로 현재 상태 확인 → 패치 생성 → 편집 →
```
validate
```
또는 재-
```
read-entity
```
로 검증.
대량 엔티티 연속 질의는 batch — 파일마다 매번 단발 호출하면 콜드 스타트 × N.

읽기 전용이 아니다 — 편집도 지원

이전 버전 스킬과 달리 이제 CLI 가 다음을 지원한다:

엔티티 메타 편집:
```
edit-entity <path> --set enable=false
```

컴포넌트 값 편집:

edit-component <entity> <@type> --set Position='[1,0,0]'

엔티티 CRUD:
```
add-entity
```
/
```
remove-entity
```
/
```
rename-entity
```
컴포넌트 CRUD:
```
add-component
```
/
```
remove-component
```
```
.model
```
값 편집:
```
set <name> <json>
```
(타입 추론 +
```
--type
```
강제)
YAML 왕복:
```
export-yaml
```
/
```
import-yaml
```
/
```
build-world
```

편집 전 백업 / 커밋은 호출자 책임 — CLI 는

--output / -o

로 다른 경로에 쓰는 옵션을 제공.

포맷 참고

```
.map
```
/
```
.ui
```
/
```
.gamelogic
```
—
```
Entities[]
```
배열 + entity → component 트리 (format-refs/map-authoring.md, format-refs/ui-authoring.md)
```
.model
```
—
```
Values[]
```
오버라이드 테이블을 갖는 entity 템플릿 (format-refs/model-authoring.md)
수동 편집 가이드: docs/manual-editing.md
VFS ↔ YAML 파이프라인: docs/vfs-yaml-pipeline.md
업스트림: https://github.com/choigawoon/msw-vfs-cli (MIT, v0.5.3)

test-msw-vfs-cli

NPX Install

Tags

SKILL.md Content

MSW 에셋 CLI 래퍼 —
`@choigawoon/msw-vfs-cli`