`emdash-plugin` CLI

@emdash-cms/plugin-cli는 샌드박스 플러그인을 스캐폴드하고, 빌드하고, 검증하고, 게시합니다. 또한 퍼블리셔 로그인, 패키지 프로필, 레지스트리 탐색 및 자동화된 릴리스를 관리합니다. 설치된 바이너리 파일 이름은 emdash-plugin입니다.

이 CLI는 패키지 프로필 및 릴리스의 퍼블리셔 신원으로 Atmosphere 계정을 사용합니다.

CLI 설치

pnpm dlx @emdash-cms/plugin-cli init로 생성된 플러그인에는 이미 고정된 개발 종속성으로 CLI가 포함되어 있습니다. 다른 명령을 사용하기 전에 기존 플러그인에 추가하세요:

pnpm add -D @emdash-cms/plugin-cli

예제는 pnpm exec emdash-plugin을 사용하므로 각 명령은 플러그인에 설치된 버전을 실행합니다. 반복되는 빌드, 로그인 또는 릴리스 명령이 아닌 일회성 init 명령에는 pnpm dlx를 사용하세요.

명령어

CLI는 다음 명령을 제공합니다:

emdash-plugin init [name]                    새 샌드박스 플러그인 스캐폴드
emdash-plugin build                          dist/ 빌드 (plugin.mjs, manifest.json, index.mjs)
emdash-plugin dev                            소스를 감시하고 변경 시 재빌드
emdash-plugin bundle                         dist/ + 자산을 레지스트리 tarball로 패킹
emdash-plugin validate [path]                emdash-plugin.jsonc를 스키마에 대해 검증
emdash-plugin publish                        빌드, 업로드, 릴리스 게시
emdash-plugin update-package [--yes]         패키지 프로필 변경 사항 미리보기 또는 적용
emdash-plugin profile setup                  위임 릴리스를 위한 서명된 패키지 프로필 준비
emdash-plugin release setup                  위임 릴리스 GitHub Actions 워크플로우 생성
emdash-plugin release plan                   GitHub Actions를 위한 리포지토리 릴리스 계획
emdash-plugin release prepare <slug[@ver]>   GitHub Actions를 위한 하나의 리포지토리 패키지 준비
emdash-plugin login <handle-or-did>          Atmosphere 계정으로 로그인
emdash-plugin logout [--did <did>]           활성 세션 취소
emdash-plugin whoami                         저장된 세션 표시
emdash-plugin switch <did>                   활성 퍼블리셔 세션 전환
emdash-plugin search <query>                 레지스트리 자유 텍스트 검색
emdash-plugin info <handle-or-did> <slug>    패키지 세부 정보 또는 리스팅 확인 상태 표시

현재 인수 및 플래그는 emdash-plugin <command> --help를 실행하세요. validate, publish, update-package, search, info, login, whoami를 포함한 스크립트용 명령은 도움말에 --json이 나열된 경우 JSON 출력을 제공합니다. 디스커버리 명령은 --registry-url <url> 또는 EMDASH_REGISTRY_URL 환경 변수를 허용합니다.

사람이 읽을 수 있는 출력은 레지스트리 패키지를 @<publisher-handle>/<slug>로 식별합니다. 빌드 진단에서 npm 패키지 이름을 표시해야 하는 경우 npm package로 레이블이 지정됩니다.

다음 예는 대부분의 플러그인이 package.json에 추가하는 두 가지 스크립트를 보여줍니다:

{
	"scripts": {
		"build": "emdash-plugin build",
		"dev": "emdash-plugin dev"
	}
}

init

init로 새 플러그인을 생성합니다:

pnpm dlx @emdash-cms/plugin-cli init my-plugin

이것은 emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, workerd 기반 테스트, README, AGENTS.md, 로컬 creating-plugins 스킬 및 패키지 관리자 구성을 스캐폴드합니다. .agents/skills와 .claude/skills는 정식 skills 디렉터리에 링크되고, .claude/CLAUDE.md는 AGENTS.md에 링크되므로 Codex와 Claude는 동일한 프로젝트 가이던스를 사용합니다. 소스는 SandboxedPlugin 타입 상수에 할당되고 기본으로 내보내진 하나의 라우트로 시작합니다. 테스트는 EmDash의 프로덕션 샌드박스 래퍼 및 호스트 브리지를 통해 해당 라우트를 호출합니다.

대화형 설정은 퍼블리셔, 작성자, 보안 연락처 및 소스 리포지토리를 묻고, 작성하기 전에 완전한 프로젝트 요약을 표시합니다. 필수 필드는 건너뛸 수 없습니다.

CLI는 npm, pnpm, Yarn 또는 Bun이 실행했는지 감지하고 일치하는 명령을 생성합니다. --package-manager로 선택을 재정의합니다. pnpm 스캐폴드에는 esbuild에 필요한 검토된 빌드 스크립트 정책이 포함되어 있습니다.

비대화형 설정에는 명시적인 소유권 메타데이터가 필요합니다. 스크립트에서 다음 형식을 사용하세요:

pnpm dlx @emdash-cms/plugin-cli init my-plugin --yes \
  --publisher did:plc:abc123def456 \
  --author-name "Jane Doe" \
  --security-email security@example.com

활성 퍼블리셔 세션 및 로컬 Git 작성자 또는 리포지토리 메타데이터에 옵트인하려면 --use-detected를 전달하세요. 해당 플래그 없이 --yes는 신원을 포함하는 로컬 기본값을 복사하지 않습니다.

build

build는 emdash-plugin.jsonc, src/plugin.ts 및 선택적 형제 package.json을 읽고 다음 파일을 생성합니다:

dist/는 빌드 출력입니다. 커밋하지 마세요. 스캐폴드의 .gitignore는 이를 제외합니다. npm 패키지를 패킹하거나 게시하기 전에 emdash-plugin build를 실행하여 files 목록에 포함할 생성된 아티팩트를 준비하세요.

dev

src/**, emdash-plugin.jsonc, package.json을 감시하고, 150ms에서 재빌드를 디바운싱합니다. 재빌드는 직렬화됩니다. 실패한 재빌드에서는 마지막 양호한 dist/를 그대로 유지하므로 워크스페이스/파일 링크를 통해 플러그인을 가져오는 사이트는 다음 성공적인 빌드까지 계속 작동합니다. Ctrl-C로 깨끗하게 종료합니다.

플러그인 디렉터리에서 pnpm dev를 실행하고 pnpm add file:../path/to/plugin으로 사이트에 설치하여 실제 사이트에 대해 개발하세요. 플러그인의 기본 내보내기를 emdash({ sandboxed: [...] })로 가져옵니다. 첫 번째 플러그인 튜토리얼은 완전한 설정을 보여줍니다.

validate

현재 디렉터리의 매니페스트를 검증하거나 다른 플러그인 디렉터리를 전달하세요:

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # 특정 디렉터리

매니페스트의 교차 필드 규칙을 포함하는 tsc 스타일 file:line:column 진단을 통한 오프라인 스키마 검사. 네트워크 없음. 프리커밋 또는 CI 게이트로 적합합니다. 매니페스트 참조를 참조하세요.

bundle

bundle은 build 위에 있는 얇은 패키징 단계입니다:

--validate-only는 tarball 생성을 건너뛰지만 dist/ 아티팩트는 여전히 생성합니다. “검증”은 “먼저 빌드”를 의미합니다.

publish

publish는 플러그인을 빌드하고 검증하며, 패키지 및 리스팅 이미지를 PDS에 업로드한 다음 릴리스 레코드를 작성합니다.

emdash-plugin login alice.example.com
emdash-plugin publish

publish는 프로필 필드에 대한 매니페스트를 읽고 퍼블리셔 고정을 시행합니다. 라이선스, 작성자, 보안 연락처 및 기타 패키지 정보를 매니페스트에 보관하세요. 이전 프로필 플래그와 --no-manifest는 레거시 스크립트 게시에 계속 사용할 수 있습니다. 이러한 흐름 중 하나를 유지하기 전에 publish --help를 확인하세요.

외부에서 호스팅되는 패키지 번들을 사용하려면 --url <https-url>을 전달하세요. CLI는 게시하기 전에 URL을 다운로드하고 검증합니다. 로컬 tarball이 다운로드된 바이트와 일치하는지 확인하려면 --local <path>를 추가하세요.

완전한 로컬 릴리스 흐름은 번들링 및 게시를 참조하세요.

info

info는 애그리게이터에서 승인된 패키지 세부 정보를 표시합니다. 게시 후 릴리스 버전과 --watch를 전달하여 현재 프로필 및 릴리스 리스팅 확인을 팔로우하세요:

emdash-plugin info plugins.emdashcms.com audit-log --version 0.2.2 --watch

승인 전에 명령은 레이블러에서 직접 상태를 읽고 패키지 식별자 및 확인 상태만 출력합니다. 애그리게이터에서 승인되지 않은 패키지 메타데이터를 반환하지 않습니다. 패키지와 릴리스가 공개되면 승인된 세부 정보와 정식 플러그인 페이지 URL을 출력합니다. Ctrl-C로 감시를 중지해도 게시된 레코드나 리스팅 확인에 영향을 미치지 않습니다.

다른 레이블러를 사용하는 레지스트리를 확인할 때는 --labeler-url <origin> 또는 EMDASH_LABELER_URL을 사용하세요.

update-package

update-package를 사용하여 릴리스를 생성하지 않고 기존 패키지 프로필을 변경하세요. emdash-plugin.jsonc의 프로필 필드를 읽고, 현재 서명된 프로필을 가져와서 제안된 변경 사항을 출력합니다:

emdash-plugin update-package

--yes를 전달하지 않으면 명령은 드라이 런입니다:

emdash-plugin update-package --yes

쓰기는 현재 레코드 CID를 전제 조건으로 사용합니다. 명령이 프로필을 읽은 후 다른 프로세스가 프로필을 변경하면 업데이트는 새 레코드를 덮어쓰는 대신 STALE_RECORD로 실패합니다. 매니페스트에서 선택적 속성을 제거해도 게시된 값은 변경되지 않습니다. 의도한 대체를 명시적으로 설정하세요.

profile setup

profile setup은 자동화된 릴리스를 위한 퍼블리셔 소유 패키지 프로필을 준비합니다. emdash-plugin.jsonc에서 누락된 프로필을 생성하거나 패키지 메타데이터를 교체하지 않고 기존 유효한 프로필에 위임 릴리스 설정을 추가합니다.

플러그인 디렉터리에서 대화형 설정을 실행하세요. 모노레포의 다른 곳에서 --dir <plugin-directory>를 전달하세요:

emdash-plugin profile setup

명령은 프로필을 작성하기 위해 활성 CLI 로그인을 사용합니다. 다른 서명된 리포지토리를 교체하는 것을 거부합니다. 리포지토리, 승인자 및 패키지 메타데이터를 유지하면서 서명된 출처 정책을 변경하려면 --provenance required|optional로 다시 실행하세요. 활성 계정이 매니페스트 퍼블리셔와 일치하지 않으면 emdash-plugin switch <did>를 실행하세요. 출처 기반 릴리스의 경우 프로필을 게시한 후 emdash-plugin release setup을 실행하세요.

release setup

release setup은 하나의 플러그인 디렉터리에서 패키지 프로필 설정을 실행한 다음 Git 리포지토리 루트에 하나의 공유 .github/workflows/emdash-release.yml을 생성합니다. 중첩된 플러그인 패키지는 동일한 워크플로우를 재사용합니다. 플러그인 디렉터리에서 실행하거나 --dir <plugin-directory>를 전달하세요. 리포지토리 루트는 준비할 패키지 프로필을 식별하지 않습니다.

emdash-plugin release setup

profile setup 플래그와 다음 워크플로우 옵션을 허용합니다:

설정이 대화형 터미널에서 Changesets를 감지하면 EmDash 플러그인을 어떻게 릴리스할지 묻습니다. Changesets 릴리스 팔로우는 emdash-plugin.jsonc를 포함하는 패키지에 대해 동일한 버전을 게시합니다. 다른 선택 사항은 <slug>@<version> 태그를 따르거나 수동 실행만 허용합니다. 비대화형 사용에서 auto는 유효한 루트 구성이 존재하는 경우 Changesets를 선택하고 그렇지 않으면 패키지 태그를 선택합니다.

Changesets 변형은 재사용 가능한 워크플로우입니다. 기존 Changesets 게시 작업 후에 하나의 호출자 작업을 추가하고 공식 게시된 패키지 JSON 출력을 전달하세요. 프라이빗 EmDash 전용 패키지에는 privatePackages.version: true 및 privatePackages.tag: true가 필요합니다. 설정은 두 옵션 중 하나가 누락된 경우 경고합니다.

명령은 생성된 워크플로우를 푸시하지 않습니다. 첫 번째 자동화된 실행은 GitHub OpenID Connect를 사용하여 리포지토리 연결 요청을 생성합니다. Actions 시크릿은 필요하지 않습니다. 워크플로우를 검토하고, 릴리스 서비스를 승인하고, 리포지토리를 연결하고, 첫 번째 릴리스를 게시하려면 자동화된 플러그인 릴리스를 참조하세요.

release plan

release plan은 생성된 워크플로우에서 사용됩니다. --published-packages <json>을 사용하면 Changesets Action 출력을 emdash-plugin.jsonc를 포함하는 패키지에 매핑하고, 버전을 확인하고, JSON 선택자 행렬을 GITHUB_OUTPUT에 작성합니다. --package <slug[@version]>을 사용하면 하나의 수동 선택자를 검증합니다. 명령은 패키지를 빌드하거나 게시하지 않습니다.

release prepare

release prepare는 생성된 워크플로우의 패키지 리졸버입니다. 리포지토리에서 하나의 플러그인 매니페스트를 찾고, 선택적 태그 버전을 확인하고, 패키지를 빌드하고, 패키지, 퍼블리셔, 디렉터리 및 번들 출력을 GITHUB_OUTPUT에 작성합니다.

생성된 워크플로우는 패키지 태그를 자동으로 전달합니다:

emdash-plugin release prepare gallery@1.2.3

수동 워크플로우 실행의 경우 평범한 플러그인 ID를 전달하세요. 명령은 해당 패키지의 매니페스트에서 버전을 사용합니다. 중복 플러그인 ID, 누락된 패키지 및 버전 불일치는 출처가 생성되기 전에 실패합니다.

프로그래매틱 API

Node.js에서 CLI의 프로그래매틱 함수를 가져와서 플러그인을 빌드하거나 번들로 만드세요:

import { buildPlugin, bundlePlugin } from "@emdash-cms/plugin-cli";

await buildPlugin({ dir: "./my-plugin" });
const result = await bundlePlugin({ dir: "./my-plugin" });

디스커버리 및 자격 증명 헬퍼의 경우 @emdash-cms/registry-client에서 가져오세요.