E EmDash CMS Everything Guides, use cases, plugins, templates
한국어

번들 및 게시

이 페이지

동작하는 샌드박스 플러그인을 게시하여 다른 사이트가 설치할 수 있게 합니다. 게시는 샌드박스만 해당합니다. 네이티브 플러그인은 npm으로 배포합니다.

CLI에서 직접 게시하거나, 자동화된 릴리스 서비스를 사용해 GitHub Actions에서 빌드하고 게시합니다. 두 경로 모두 릴리스를 Atmosphere 계정에 기록합니다. CLI 직접 --url 경로를 명시적으로 선택할 때만 별도의 아티팩트 호스트가 필요합니다.

사전 요구 사항

  • slug, publisher, license, 작성자(author 또는 authors), 보안 연락처(security 또는 securityContacts)가 있는 유효한 emdash-plugin.jsonc. 확인하려면 emdash-plugin validate를 실행하세요.
  • version(package.json, 또는 레지스트리 전용 플러그인의 경우 매니페스트).
  • 게시할 Atmosphere 계정.

게시 방법 선택

두 방법 모두 게시자 소유의 패키지 및 릴리스 레코드를 만듭니다. 릴리스 빌드가 실행될 위치와 이를 승인할 자격 증명을 선택하세요.

방법사용 시점계정 액세스
emdash-plugin publish컴퓨터나 다른 신뢰할 수 있는 환경에서 빌드하고 게시할 때.로컬 CLI 세션이 패키지 프로필, 릴리스, blob을 기록합니다.
자동화된 릴리스GitHub Actions가 버전 태그 또는 수동 워크플로 실행에서 릴리스를 빌드해야 할 때.로컬 CLI가 프로필을 부트스트랩하고, 릴리스 서비스가 create-only 릴리스 및 blob 권한을 보유합니다.

Atmosphere 계정

게시는 Atmosphere 계정 아래에서 합니다. 이는 Bluesky 및 기타 AT Protocol 네트워크 앱에서 사용되는 사용자 소유의 휴대용 신원입니다. 계정은 네트워크의 단일 로그인이며 어디서나 같은 @handle을 갖고, 신원과 데이터는 단일 앱에 묶이지 않습니다. EmDash는 이 계정을 게시자 신원으로 사용합니다. 게시하는 각 릴리스는 당신으로 서명된, 당신 계정상의 레코드입니다.

EmDash는 사이트용 Atmosphere 로그인과 같은 Atmosphere 계정을 사용합니다.

기존 계정 사용

이미 Bluesky 계정이나 다른 Atmosphere 계정이 있다면 해당 핸들로 로그인하세요.

emdash-plugin login alice.bsky.social

그러면 브라우저에서 계정 제공자의 로그인 페이지가 열립니다. EmDash는 비밀번호를 절대 보지 않습니다. emdash-plugin whoami는 저장된 세션을 나열하고, emdash-plugin switch <did>는 활성 세션을 전환합니다.

계정 등록

아직 Atmosphere 계정이 없다면 어떤 제공자든 통해 만든 뒤 emdash-plugin login <your-handle>을 실행하세요. 선택지:

  • Bluesky 같은 앱. Bluesky에 가입하면 Bluesky가 호스팅하는 Atmosphere 계정이 만들어집니다. 가장 빠른 경로입니다.
  • 독립 제공자. 커뮤니티 또는 개인정보 중심 계정 호스트. atmosphereaccount.com에서 옵션을 살펴보세요.
  • 셀프 호스트. 자체 제공자를 운영해 신원과 데이터를 완전히 제어합니다.

무엇을 선택하든, 그 계정의 @handle을 emdash-plugin login에 전달하고, 계정 DID를 매니페스트의 publisher로 고정합니다.

플러그인 디렉터리에서 게시

한 번 로그인한 뒤 emdash-plugin.jsonc가 있는 디렉터리에서 게시하세요.

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

publish는 bundle과 같은 빌드 및 검증 검사를 실행하고, gzip 아카이브를 만들어 personal data server(PDS)에 업로드하며, 선언된 리스팅 이미지를 업로드하고, 릴리스 레코드를 기록합니다.

정규 HTTPS 리포지토리를 사용할 수 있으면 명령이 선택적 provenance와 함께 패키지 프로필에 추가합니다. 리포지토리 메타데이터가 없는 프로필도 provenance 없는 릴리스를 허용합니다. profile setup이 패키지를 provenance 필수로 구성했다면, 생성된 GitHub Actions 워크플로를 통해 게시하세요.

Bundle

bundle은 build를 실행하고, 검증하고, 에셋을 모아 tarball을 만듭니다. tarball 안에서 plugin.mjs는 backend.js(레지스트리가 기대하는 파일명)로 패키징됩니다.

명령은 다음 플래그를 받습니다.

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]
플래그기본값설명
--dir현재 디렉터리플러그인 소스 디렉터리.
--out-dir, -odisttarball 출력 디렉터리.
--validate-onlyfalsetarball은 건너뛰지만 dist/ 아티팩트는 계속 생성합니다.

tarball 내용

파일필수설명
manifest.json예생성된 매니페스트: id, version, capabilities, hosts, 소스 코드에서 읽은 hooks와 routes. 손으로 유지하지 않습니다.
backend.js예빌드된 자체 완비 런타임 파일(dist/plugin.mjs).
README.md아니요플러그인 문서.
icon.png아니요관례적 번들 아이콘. 읽을 수 있는 PNG여야 합니다. 256×256 권장.
screenshots/아니요최대 8개의 .png, .jpg 또는 .jpeg 파일. 1920×1080 이하 권장.

검증

bundle(및 --validate-only)은 다음을 확인합니다.

  • 크기 한도(RFC 0001, 압축 해제): 합계 ≤ 256 KB, 파일당 ≤ 128 KB, ≤ 20개 파일. gzip tarball은 그 일부입니다.
  • backend.js에 Node 내장 없음 — 샌드박스 코드는 fs, path, child_process 등을 가져올 수 없습니다. 웹 API를 쓰거나 그 로직을 네이티브 플러그인으로 옮기세요.
  • capabilities 건전성 — 이름은 인식된 집합에 있어야 합니다.
  • 신뢰 계약 일관성 — Capabilities 및 hosts의 교차 규칙 network:request / allowedHosts.
  • 관례적 번들 에셋 — 읽을 수 없는 icon.png 또는 스크린샷은 건너뜁니다. 아이콘이 256×256이 아니거나 스크린샷이 1920×1080을 넘으면 CLI가 경고하지만, 치수만으로 번들이 실패하지는 않습니다. 포함된 각 파일은 계속 압축 해제 파일 및 크기 한도에 포함됩니다.

게시 전에 tarball을 검사하려면 내용을 나열하세요.

emdash-plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz

Publish

현재 소스를 게시하고 아티팩트를 PDS에 호스팅합니다.

emdash-plugin publish

다음 매니페스트 블록은 리스팅 이미지를 추가합니다. 경로는 emdash-plugin.jsonc 기준 상대 경로입니다. PNG, JPEG, WebP를 지원합니다.

{
  "release": {
    "artifacts": {
      "icon": { "file": "./icon.png" },
      "banner": { "file": "./banner.webp" },
      "screenshots": [
        { "file": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

매니페스트에 선언된 리스팅 이미지는 tarball에 포함된 관례적 icon.png 및 screenshots/ 파일과 다릅니다. 게시는 선언된 각 이미지를 게시자의 PDS에 업로드하고 그 blob 참조를 릴리스 레코드에 기록합니다. 각 이미지는 1 MiB, 각 변 8,192픽셀로 제한됩니다. 한 릴리스는 최대 8개의 스크린샷을 선언할 수 있습니다. 전체 형태는 릴리스 필드를 보세요.

publish가 하는 일:

  1. 플러그인을 빌드하고, 압축 해제 한도를 검증하고, gzip 아카이브를 만듭니다.
  2. Atmosphere 계정 세션을 재개하고 게시자 고정을 확인합니다.
  3. OAuth 부여에 패키지 및 이미지 blob 스코프가 포함되는지 확인합니다.
  4. 패키지와 선언된 이미지를 PDS에 업로드하고, 반환된 각 blob CID를 업로드한 바이트와 대조합니다.
  5. 첫 게시 시 패키지 프로필을 만들고 불변 릴리스 레코드를 기록합니다.

CLI는 게시된 패키지를 @<publisher-handle>/<slug>로 식별하고, 승인 후 사용 가능해지는 공개 페이지를 출력하며, emdash-plugin info … --version <version> --watch 명령을 제공합니다. 이 명령은 레이블러의 현재 검사를 직접 읽습니다. 미승인 패키지 메타데이터는 애그리게이터 응답과 공개 플러그인 사이트에서 계속 제외됩니다.

기존 로그인이 blob 게시보다 이전이면 publish는 MISSING_BLOB_SCOPE를 보고합니다. emdash-plugin logout을 실행한 뒤 다시 로그인하여 새 스코프를 승인하세요.

외부 패키지 URL 사용

패키지 번들이 이미 HTTPS로 제공되거나 계정 제공자가 gzip blob을 받지 않으면 --url을 전달하세요.

emdash-plugin publish --url https://downloads.example.com/gallery-1.0.0.tar.gz

CLI는 URL을 다운로드하고, 제공된 번들을 검증하고, 체크섬을 계산합니다. 이 경로에서는 패키지 blob을 업로드하지 않습니다. 리스팅 이미지는 계속 PDS blob을 사용합니다.

호스팅된 바이트를 로컬 tarball과 비교하려면 --local을 추가하세요.

emdash-plugin publish \\
  --url https://downloads.example.com/gallery-1.0.0.tar.gz \\
  --local dist/gallery-1.0.0.tar.gz

버전은 기본적으로 불변

emdash-plugin publish는 같은 slug와 버전의 기존 릴리스 교체를 거부합니다. 다시 게시하기 전에 version을 올리세요. 빌드는 package.json에서 version을 읽습니다(버전 값은 하나로 유지 참고). 확장된 신뢰 계약에는 major, 새 hooks 또는 routes에는 minor, 수정에는 patch를 올리세요.

게시자 불일치

publish가 MANIFEST_PUBLISHER_MISMATCH로 실패하면, 활성 세션이 매니페스트에 고정된 publisher와 다른 Atmosphere 계정입니다. emdash-plugin switch <did>로 고정된 계정으로 전환하거나, 실제로 새 계정으로 플러그인을 옮기는 경우 매니페스트의 publisher를 업데이트하세요. 세션 관리는 기존 계정 사용을 보세요.

다음에 읽을 내용