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가 프로필을 준비하고, 릴리스 서비스는 릴리스와 blob을 생성하는 권한만 보유합니다.

Atmosphere 계정

게시는 Atmosphere 계정 으로 합니다. 이는 Bluesky를 비롯해 AT Protocol 네트워크의 여러 앱에서 쓰이는, 이동 가능하며 사용자가 소유하는 ID입니다. 계정 하나가 네트워크 전체에서 쓰는 단일 로그인이 되며 어디서나 같은 @handle을 사용하고, ID와 데이터가 특정 앱에 묶이지 않습니다. EmDash는 이 계정을 게시자 ID로 사용합니다. 게시하는 모든 릴리스는 사용자 본인 계정에 있는 레코드이며, 본인 명의로 서명됩니다.

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에서 선택지를 살펴보세요.
  • 자체 호스팅. 직접 제공자를 운영해 ID와 데이터를 완전히 통제합니다.

어떤 것을 선택하든 emdash-plugin login에 전달하는 값은 그 계정의 @handle이고, 매니페스트에서 publisher로 고정하는 값은 그 계정의 DID입니다.

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

한 번 로그인한 다음, emdash-plugin.jsonc가 있는 디렉터리에서 게시합니다.

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

publish는 bundle과 같은 빌드 및 검증 검사를 실행하고, gzip 아카이브를 만들어 개인 데이터 서버(PDS)에 업로드합니다. 선언된 목록용 이미지도 업로드하고 릴리스 레코드를 기록합니다.

정식 HTTPS 저장소를 사용할 수 있으면 이 명령은 선택적 출처 증명과 함께 이를 패키지 프로필에 추가합니다. 저장소 메타데이터가 없는 프로필은 출처 증명 없는 릴리스도 허용합니다. profile setup에서 패키지가 출처 증명을 요구하도록 설정했다면, 대신 생성된 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, 버전, capability, 호스트, 그리고 소스에서 읽은 훅과 라우트. 직접 관리할 필요가 없습니다.
backend.js예빌드된 자체 완결형 런타임 파일(dist/plugin.mjs).
README.md아니요플러그인 문서.
icon.png아니요관례적인 번들 아이콘. 읽을 수 있는 PNG여야 하며 256×256을 권장합니다.
screenshots/아니요최대 여덟 개의 .png, .jpg, .jpeg 파일. 1920×1080 이하를 권장합니다.

검증

bundle(및 --validate-only)은 다음을 검사합니다.

  • 크기 제한(RFC 0001, 압축 해제 기준): 전체 ≤ 256 KB, 파일당 ≤ 128 KB, ≤ 20개 파일. gzip으로 압축된 tarball은 그중 일부에 불과합니다.
  • backend.js에 Node 내장 모듈이 없을 것 — 샌드박스 코드는 fs, path, child_process 등을 import할 수 없습니다. Web API를 사용하거나 해당 로직을 네이티브 플러그인으로 옮기세요.
  • Capability 타당성 — 이름은 인식되는 집합에 속해야 합니다.
  • 신뢰 계약 일관성 — Capability와 호스트의 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": "./images/editor.png" },
        { "file": "./images/settings.jpg", "lang": "en" }
      ]
    }
  }
}

게시하면 선언된 각 이미지가 게시자의 PDS에 업로드되고, 그 blob 참조가 릴리스 레코드에 기록됩니다. 각 이미지는 1 MiB, 가로·세로 각각 8,192픽셀로 제한되며, 한 릴리스에서 선언할 수 있는 스크린샷은 최대 여덟 장입니다. bundle은 매니페스트에서 선언했는지와 관계없이 관례적인 icon.png와 screenshots/의 PNG, JPEG 파일도 tarball에 패킹하며, 패킹된 각 파일은 파일당 128 KB, 전체 256 KB의 크기 제한에 포함됩니다. 선언한 스크린샷은 images/ 같은 다른 폴더에 보관하세요. 전체 형태는 릴리스 필드를 참조하세요.

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는 같은 슬러그와 버전의 기존 릴리스를 교체하기를 거부합니다. 다시 게시하기 전에 version을 올리세요. 빌드는 package.json에서 version을 읽습니다(버전 값은 한 곳에서만 관리 참조). 신뢰 계약을 넓힐 때는 메이저, 새 훅이나 라우트에는 마이너, 수정에는 패치를 올립니다.

게시자 불일치

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

다음에 읽을 내용