아임웹 마스터 CLI (imweb-master-cli)

NPM

https://www.npmjs.com/package/imweb-master-cli

아임웹 커스텀 개발을 위한 워크스페이스를 손쉽게 초기화하고 관리할 수 있는 CLI 도구입니다.

개발 환경

이 CLI 도구는 아임웹 커스텀 개발 환경에 최적화되어 있습니다.

로컬 소스에서 직접 사용하기 (npm 설치 없음)

이 저장소의 imweb-master.js는 실행 가능한 CLI 파일이므로 npm install -g나 npm link 없이 로컬 경로를 직접 지정해 사용할 수 있습니다.

Zsh 사용자는 ~/.zshrc에 다음 내용을 추가합니다.

export IMWEB_MASTER_HOME="/absolute/path/to/0.1_imweb-master"

imweb-master() {
  "$IMWEB_MASTER_HOME/imweb-master.js" "$@"
}

현재 저장소가 /Users/citrusq/workspace/imweb-custom/0.1_imweb-master에 있다면 IMWEB_MASTER_HOME은 다음과 같이 지정합니다.

export IMWEB_MASTER_HOME="/Users/citrusq/workspace/imweb-custom/0.1_imweb-master"

설정을 현재 터미널에 적용하고 실행 여부를 확인합니다.

source ~/.zshrc
type imweb-master
imweb-master --help

참고: 이 방식은 CLI 자체를 npm에 설치하지 않습니다. 다만 imweb-master init은 생성된 프로젝트의 개발 의존성을 설치하기 위해 현재 구현상 npm install을 실행합니다.

주요 기능

• 프로젝트 초기화: init 명령어로 필요한 모든 템플릿 파일과 개발 규칙을 포함한 새로운 워크스페이스를 설정합니다.
• 개발 규칙 관리: push-rules와 pull-rules 명령어를 통해 여러 프로젝트 간의 개발 규칙(.imweb)을 일관성 있게 동기화합니다.
• 에이전트 규칙 관리: push-agent와 pull-agent 명령어로 프로젝트 루트의 AGENTS.md를 동기화합니다.
• 템플릿 동기화: push-template과 pull-template 명령어로 핵심 템플릿 파일(jsdoc.json, package.json, README.example.md)을 동기화하여 개발 환경의 일관성을 유지합니다.

설치

npm을 통해 이 도구를 전역으로 설치하여 어디서든 imweb-master 명령어를 사용할 수 있습니다.

기본 설치

npm install -g imweb-master-cli

NVM 등 여러 Node 버전을 사용하는 경우

npm install -g의 설치 위치는 활성화된 Node 버전에 따라 달라질 수 있습니다. 모든 Node 버전에서 동일한 CLI를 사용하려면 사용자 공용 경로에 설치하세요.

mkdir -p "$HOME/.local"
npm install -g --prefix "$HOME/.local" imweb-master-cli

Zsh 사용자는 ~/.zshrc에 다음 설정을 추가합니다. alias는 nvm use 실행 후 NVM의 전역 설치본이 우선되는 것을 방지합니다.

export PATH="$HOME/.local/bin:$PATH"
alias imweb-master="$HOME/.local/bin/imweb-master"

설정을 현재 터미널에 적용하고 설치 경로를 확인합니다.

source ~/.zshrc
type imweb-master

정상적으로 설정되면 imweb-master가 $HOME/.local/bin/imweb-master를 가리킵니다.

업데이트할 때도 같은 공용 경로를 지정합니다.

npm install -g --prefix "$HOME/.local" imweb-master-cli@latest

사용법

1. 새로운 워크스페이스 초기화

새로운 프로젝트를 시작할 디렉터리로 이동한 후, 다음 명령어를 실행하세요.

imweb-master init

이 명령어는 다음 작업을 자동으로 수행합니다.

1. 프로젝트 템플릿 파일 복사
2. .imweb 폴더 생성 및 개발 규칙 복사
3. package.json의 프로젝트 이름 설정
4. 필요한 npm 의존성 설치

2. 개발 규칙 동기화

현재 프로젝트의 규칙을 원본으로 푸시

# 일반 프로젝트 폴더 내에서 실행
imweb-master push-rules

# 다른 위치에서 특정 프로젝트를 대상으로 실행
imweb-master push-rules /path/to/project

원본 규칙을 현재 프로젝트로 가져오기

# 일반 프로젝트 폴더 내에서 실행
imweb-master pull-rules

# 다른 위치에서 특정 프로젝트를 대상으로 실행
imweb-master pull-rules /path/to/project

3. AGENTS.md 동기화

현재 프로젝트의 AGENTS.md를 원본으로 푸시

# 일반 프로젝트 폴더 내에서 실행
imweb-master push-agent

# 다른 위치에서 특정 프로젝트를 대상으로 실행
imweb-master push-agent /path/to/project

원본 AGENTS.md를 현재 프로젝트로 가져오기

# 일반 프로젝트 폴더 내에서 실행
imweb-master pull-agent

# 다른 위치에서 특정 프로젝트를 대상으로 실행
imweb-master pull-agent /path/to/project

4. 템플릿 파일 동기화

현재 프로젝트의 템플릿을 원본으로 푸시

# 일반 프로젝트 폴더 내에서 실행
imweb-master push-template

# 다른 위치에서 특정 프로젝트를 대상으로 실행
imweb-master push-template /path/to/project

원본 템플릿을 현재 프로젝트로 가져오기

# 일반 프로젝트 폴더 내에서 실행
imweb-master pull-template

# 다른 위치에서 특정 프로젝트를 대상으로 실행
imweb-master pull-template /path/to/project

참고: push/pull 명령어는 개별 프로젝트 폴더 내에서 실행하여 원본과 동기화하는 것이 주된 목적입니다. imweb-master 루트에서 이 명령어들을 사용할 경우, 동기화할 대상 프로젝트의 경로를 반드시 지정해야 합니다.

npm 퍼블리싱

이 프로젝트는 스코프 없는 공개 패키지인 imweb-master-cli로 배포됩니다. 배포하려면 해당 패키지의 npm 소유자 또는 관리 권한이 있어야 하며, npm 계정에 2단계 인증(2FA)을 설정해야 합니다.

1. 로그인 및 권한 확인

npm login
npm whoami
npm owner ls imweb-master-cli

이미 로그인되어 있다면 npm login은 생략할 수 있습니다.

2. 배포 전 검증

저장소 루트에서 테스트를 실행하고 실제 패키지에 포함될 파일을 확인합니다.

node --test
npm pack --dry-run

package.json의 files 설정에 따라 다음 항목이 배포 대상에 포함되어야 합니다.

• imweb-master.js
• template/
• rules/
• README.md, package.json, 라이선스 등 npm이 기본으로 포함하는 파일

민감한 정보나 불필요한 파일이 출력되면 배포 전에 files, .npmignore 또는 .gitignore 설정을 수정합니다.

3. 버전 변경

npm은 이미 배포된 버전을 다시 배포할 수 없으므로 SemVer 규칙에 따라 버전을 증가시킵니다.

# 버그 수정: 0.9.5 → 0.9.6
npm version patch

# 하위 호환 기능 추가: 0.9.6 → 0.10.0
npm version minor

# 호환되지 않는 변경: 0.10.0 → 1.0.0
npm version major

npm version은 package.json과 package-lock.json의 버전을 함께 변경하고 Git 커밋과 태그를 생성하므로, 변경사항을 먼저 커밋한 깨끗한 작업 트리에서 실행하는 것을 권장합니다. 버전을 직접 수정했다면 두 파일의 버전이 일치하는지 확인합니다.

현재 배포된 버전과 로컬 배포 예정 버전은 다음 명령으로 비교할 수 있습니다.

npm view imweb-master-cli version
node -p "require('./package.json').version"

4. 공개 배포

배포 내용을 한 번 더 미리 확인한 후 퍼블리싱합니다.

npm publish --dry-run
npm publish

npm publish 과정에서 요청되면 인증 앱의 일회용 비밀번호(OTP)를 입력합니다. imweb-master-cli은 스코프 없는 패키지이므로 별도의 --access public 옵션이 필요하지 않습니다.

5. 배포 확인

npm view imweb-master-cli version
npm view imweb-master-cli dist-tags

배포 후 전역 설치본을 갱신해 동작을 확인할 수 있습니다.

npm install -g --prefix "$HOME/.local" imweb-master-cli@latest
imweb-master --help

주의: 로컬 개발용 ~/.local/bin/imweb-master가 이 저장소의 imweb-master.js를 직접 가리키는 심볼릭 링크라면, 위 전역 설치 명령이 링크를 npm 설치본으로 교체할 수 있습니다. 계속 로컬 소스를 사용할 경우 설치 후 링크를 다시 설정하세요.

자주 발생하는 오류

• You cannot publish over the previously published versions: package.json의 버전을 증가시킵니다.
• E401 Unauthorized: npm 로그인이 만료되었거나 인증 토큰이 유효하지 않습니다. npm login 후 npm whoami로 다시 확인합니다.
• E404 Not Found (publish 시): 패키지가 존재하더라도 현재 계정에 배포 권한이 없으면 발생할 수 있습니다. npm whoami와 npm owner ls imweb-master-cli 결과를 비교합니다.
• 403 Forbidden: 패키지 소유 권한, 로그인 계정, 2FA 또는 OTP를 확인합니다.
• 의도하지 않은 파일이 포함됨: npm pack --dry-run 결과를 확인하고 files 또는 ignore 설정을 수정합니다.

자세한 내용은 npm 공식 퍼블리싱 문서와 npm publish CLI 문서를 참고하세요.

라이선스

ISC