IWE npm 패키징 — Rust 바이너리·CLI/LSP/MCP 배포 구조

IWE의 npm/은 Markdown 지식 그래프를 직접 구현하는 JavaScript 앱이 아니라, Rust로 빌드된 iwe·iwes·iwec 바이너리를 플랫폼별 npm 패키지로 전달하는 배포 계층이다.[4][5]

한눈에 보기

대상: 사용자가 지정한 https://github.com/iwe-org/iwe/tree/master/npm 경로다.[1]
고정 snapshot: moving master를 그대로 근거로 삼지 않고 54074f4692142d44c74598b80abed04432112c20(chore: cut 0.19.1 changelog)에 pin했다.[2] 이 commit에는 iwe-v0.19.1, iwes-v0.19.1, iwec-v0.19.1, diwe-v0.19.1, liwe-v0.19.1 tag가 관찰됐다.[2]
저장소 정체성: IWE는 Rust·Apache-2.0 프로젝트이며, README는 로컬 Markdown 파일을 knowledge graph로 만들고 CLI·LSP·MCP로 접근한다고 설명한다.[3][4] retrieval 시점 GitHub metadata의 설명은 “LSP for your editor, CLI + MCP memory for your AI agents”였다.[3]
npm tree: 고정 commit의 npm/에는 15개 tracked file이 있다.[1] 5개 플랫폼 package manifest, @iwe-org/iwe, @iwe-org/mcp, stamp.js로 구성된다.[2]
버전 경계: 소스 tree의 npm manifest는 0.0.0 placeholder지만, release workflow가 tag에서 실제 버전을 읽어 stamping한 뒤 publish한다.[6][13] 고정 Rust workspace 버전은 0.19.1이다.[14]
검증 경계: 이 환경에서는 npm wrapper 정적 검사, package dry-run, version-stamp sandbox, npm registry npx smoke, MCP initialize handshake를 실행했다.[unverified] Rust source build/test는 host에 cargo가 없어 실행하지 못했다.[unverified]

IWE 전체에서 npm의 위치

IWE는 Markdown 파일·링크·frontmatter를 git으로 소유하면서, editor에는 LSP 기능을, AI agent에는 CLI와 MCP 구조 접근을 제공하는 로컬 지식 그래프 도구다.[4] README는 find, retrieve, tree, update, schema 등을 핵심 CLI 표면으로 소개하고, MCP·CLI가 같은 노트 구조를 사용한다고 설명한다.[4]

따라서 npm/만 읽어서 검색·refactor·schema validation의 실제 알고리즘을 재구성하면 안 된다.[4] npm package에 들어 있는 JavaScript는 실행 파일을 고르는 launcher이고, 실제 기능은 release archive에서 내려받는 Rust binary에 있다.[4][5]

패키지 구성

패키지	역할
`@iwe-org/iwe`	`iwe`, `iwes`, `iwec` 세 binary entrypoint를 제공하는 사용자용 umbrella package
`@iwe-org/cli-darwin-arm64`	macOS arm64 binary package
`@iwe-org/cli-darwin-x64`	macOS x64 binary package
`@iwe-org/cli-linux-arm64`	Linux arm64, gnu libc binary package
`@iwe-org/cli-linux-x64`	Linux x64, gnu libc binary package
`@iwe-org/cli-win32-x64`	Windows x64 binary package
`@iwe-org/mcp`	`iwec`를 `iwe-mcp`라는 별도 npx/MCP entrypoint로 노출하는 convenience package

@iwe-org/iwe는 Node >=18을 요구하고, bin에 iwe, iwes, iwec를 선언하며, 다섯 플랫폼 package를 optionalDependencies로 연결한다.[6] install script 없이 npm의 플랫폼 선택에 의존하는 설계다.[6]

@iwe-org/mcp는 Node >=18에서 동작하고 @iwe-org/iwe를 같은 버전의 dependency로 사용한다.[9] 별도 iwe-mcp bin을 제공하지만, package의 본체는 결국 umbrella package가 고른 iwec binary다.[9][10]

Node launcher의 실행 경계

npm/iwe/lib/run.js는 process.platform + '-' + process.arch를 key로 사용해 다섯 조합을 package name에 매핑한다.[7] Windows에서는 binary 이름에 .exe를 붙이고, require.resolve()로 optional dependency 안의 파일을 찾은 뒤 execFileSync()로 현재 CLI 인자를 전달하며 stdio를 상속한다.[7]

이 구현에는 두 가지 명시적 실패 경계가 있다.[7]

지원하지 않는 OS/CPU 조합이면 unsupported platform을 출력하고 종료한다.[7]
npm이 optional dependency를 생략했거나 platform package가 없으면 platform package ... is not installed를 출력하고 재설치를 안내한다.[7]

즉 --no-optional 설치는 핵심 기능을 제거할 수 있다.[6][7] 또한 source checkout에는 platform binary가 들어 있지 않으므로, 고정 tree에서 node npm/iwe/bin/iwe.js --version을 실행하면 wrapper 자체가 아니라 “platform package가 설치되지 않음”으로 종료한다.[unverified]

CLI·LSP·MCP 사용 표면

사용자용 IWE package는 다음 세 실행 파일을 한 번에 설치한다.[5]

npm install -g @iwe-org/iwe
iwe init

README가 설명하는 iwe는 Markdown knowledge base의 검색·질의·refactor·validation CLI이고, iwes는 VS Code·Neovim·Zed·Helix 등을 위한 LSP server이며, iwec는 MCP server다.[5]

MCP만 필요하면 다음처럼 별도 package를 npx로 실행할 수 있다.[8]

{
  "mcpServers": {
    "iwe": {
      "command": "npx",
      "args": ["-y", "@iwe-org/mcp"]
    }
  }
}

MCP README는 서버가 stdio로 동작하고, 시작된 working directory의 Markdown 파일을 대상으로 하며, 해당 디렉터리의 .iwe/config.toml로 동작을 조정할 수 있다고 설명한다.[8] npm/mcp/bin/iwe-mcp.js는 @iwe-org/iwe/lib/run의 run('iwec')만 호출하는 매우 얇은 bridge다.[10]

server.json은 MCP Registry 식별자를 io.github.iwe-org/iwe로 선언하고, @iwe-org/mcp를 npx runtimeHint와 stdio transport로 등록한다.[12] 최근 commit의 mcpName package metadata와 이 registry descriptor가 같은 공개 MCP 배포 표면을 가리킨다.[9][12]

Version stamping과 release pipeline

소스 package manifest의 0.0.0은 publish할 버전이 아니라 release job 전에 채워지는 placeholder다.[6][13] npm/stamp.js는 일곱 npm package의 version을 바꾸고, @iwe-org/iwe의 optional dependency와 @iwe-org/mcp의 IWE dependency도 같은 version으로 맞춘 뒤 server.json의 server/package version까지 함께 갱신한다.[11]

Rust workspace의 고정 version은 0.19.1이고 repository license는 Apache-2.0이다.[14] .release-plz.toml은 workspace의 자동 dependency/changelog 갱신을 끄고, iwe package만 v{{ version }} git release를 활성화하는 설정을 보여준다.[15]

.github/workflows/release.yaml의 Binaries workflow는 published release 또는 manual tag 입력으로 시작한다.[13] cross-compilation matrix는 Linux arm64/x64, macOS arm64/x64 및 universal macOS, Windows x64 release archive를 만든다.[13]

publish-npm job은 iwe-v로 시작하는 tag만 대상으로 release binary를 각 platform package directory에 풀고, tag에서 버전을 추출해 stamp.js를 실행한 뒤 다음 package를 순서대로 publish한다.[13]

cli-darwin-arm64
cli-darwin-x64
cli-linux-x64
cli-linux-arm64
cli-win32-x64
iwe
mcp

이미 같은 version이 npm에 있으면 skip하고, 그렇지 않으면 npm publish를 실행한다.[13] job에는 npm trusted publishing을 위한 id-token: write가 있고, 후속 npm-smoke-test는 Ubuntu·macOS·Windows에서 두 npx package의 --version을 최대 10회 재시도한다.[13]

마지막 publish-mcp-registry job은 npm smoke가 성공한 뒤 mcp-publisher login github-oidc와 mcp-publisher publish를 실행해 server.json을 MCP Registry에 등록한다.[12][13]

검증 결과

고정 source와 package 구조

fixed checkout HEAD는 54074f4692142d44c74598b80abed04432112c20이고 working tree는 clean이었다.[unverified]
commit-pinned raw manifest는 npm 15개와 supplemental release/context 5개, 총 20개 파일을 HTTP status·byte 수·SHA-256·local checkout bytes로 비교해 20/20 일치했다.[unverified]
raw capture의 현재 body SHA-256은 310ac2764084e6bd5180e2860efcb54bdb9f895a022124e549a358d7a92694d2다. 자동 asset normalization으로 README badge 링크가 local raw asset 링크로 변환된 뒤 body hash를 재계산했다.[unverified]

로컬 Node/package 검사

JavaScript 8개 파일에 node --check: 성공.[unverified]
7개 npm package에 npm pack --dry-run --ignore-scripts: 모두 성공.[unverified]
source snapshot에는 binary archive가 없으므로 platform package dry-run에는 package.json만 들어갔다.[unverified] release workflow가 archive를 먼저 풀어 넣는 이유가 이 경계다.[13][unverified]
임시 sandbox에서 node npm/stamp.js 1.2.3을 실행해 일곱 package, optional/dependency version, MCP server version이 모두 1.2.3으로 맞는 것을 확인했다.[unverified]
invalid version 입력은 usage 출력과 exit 1로 거부됐다.[unverified]

published npm runtime

retrieval 시 npm registry의 @iwe-org/iwe, @iwe-org/mcp, Linux arm64/x64·macOS arm64·Windows x64 platform package version은 모두 0.19.1이었다.[unverified]

npx --yes @iwe-org/iwe@0.19.1 --version  -> iwe 0.19.1
npx --yes @iwe-org/mcp@0.19.1 --version  -> iwec 0.19.1

깨끗한 temporary working directory에서 @iwe-org/mcp@0.19.1에 MCP initialize request를 보내 serverInfo.name = iwe, serverInfo.version = 0.19.1 응답과 iwe_find, iwe_retrieve, iwe_tree, iwe_create, iwe_update, iwe_query 등의 instruction을 확인했다.[unverified]

반대로 고정 source checkout에서 local wrapper를 직접 실행한 결과는 platform package 부재 오류였다.[unverified] 이는 source tree가 binary release artifact를 포함하지 않는다는 사실과 일치하며, 실패를 package 기능 실패로 해석하지 않았다.[unverified]

실행하지 못한 것

host에 cargo command가 없어 고정 checkout의 cargo fmt --check와 cargo test --workspace --no-fail-fast는 실행하지 못했다.[unverified] 따라서 Rust workspace build/test 성공을 주장하지 않는다.[unverified]
각 OS의 native installation, npm trusted-publishing 권한, GitHub Actions 전체 release workflow, npm Registry 재게시, MCP Registry publish 자체는 실행하지 않았다.[unverified]
published npx smoke와 MCP initialize는 현재 registry release 0.19.1에 대한 runtime evidence이지, 고정 commit의 Rust binary를 이 host에서 새로 빌드했다는 증거는 아니다.[unverified]

판단과 주의점

좋은 점: npm package 표면은 작고 명확하다.[6] Node launcher가 platform selection만 담당하고 실제 기능은 Rust binary에 남아 있어 npm package가 복잡한 런타임 의존성을 끌어안지 않는다.[7]
공급 경계: optionalDependencies가 누락되면 umbrella package가 설치되어도 실행되지 않는다.[6] 사내 mirror나 --no-optional 정책에서는 다섯 platform package의 보존 여부를 별도로 확인해야 한다.[7]
릴리스 일관성: stamp.js가 seven packages와 MCP Registry descriptor version을 한 번에 바꾸고, workflow가 publish 전 release binary를 package directory에 주입한다.[11][12] 이 두 단계 중 하나라도 빠지면 npm wrapper와 binary/registry version이 어긋날 수 있다.[13]
범위 제한: npm/ capture만으로 Rust core의 graph semantics, schema validation, LSP protocol, MCP tool implementation 품질을 평가할 수 없다.[4] 그 부분은 별도 Rust source/test 조사 대상이다.[14]

Sources

description	IWE의 npm 경로가 플랫폼별 Rust 바이너리와 Node thin wrapper를 배포하는 구조와 release·MCP 검증 경계를 정리한다.
tags	ai-agents, dev-tools, open-source, rust, cli
aliases	IWE npm, @iwe-org/iwe, @iwe-org/mcp

LLM Wiki

탐색기