공식 플러그인

공식 플러그인은 pubm와 함께 유지보수되며, 핵심 프로젝트와 같은 릴리스 및 호환성 기대치를 따릅니다. 처음부터 직접 플러그인을 만들지 않고도 안정적으로 지원되는 통합이 필요할 때 사용합니다.

`@pubm/plugin-brew`

@pubm/plugin-brew는 CLI 프로젝트가 각 릴리스와 함께 Homebrew formula를 동기화하는 데 도움을 줍니다. PR을 연 뒤 파이프라인이 실패하면 해당 Homebrew PR을 닫는 롤백 액션을 등록합니다.

잘 맞는 경우

Homebrew를 통해 CLI 바이너리를 배포할 때
전용 tap 저장소를 자동으로 업데이트할 때
release asset과 formula checksum을 맞춰 둘 때

일반적인 설정

import { defineConfig } from "@pubm/core";
import { brewTap } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewTap({
      formula: "Formula/my-tool.rb",
      repo: "https://github.com/my-org/homebrew-tap",
    }),
  ],
});

옵션

옵션	타입	설명
`formula`	`string`	저장소 루트 기준 formula 경로
`repo`	`string`	선택적 remote tap 저장소 URL. 생략하면 현재 저장소를 사용합니다.
`packageName`	`string`	선택적 package name 필터. 지정하면 이 package name과 일치하는 릴리스에서만 플러그인이 실행됩니다. 모노레포에 유용합니다.
`assetPlatforms`	`Record<string, (asset: ReleaseAsset) => boolean>`	선택적 커스텀 플랫폼 매처. 기본 `os + arch` 매칭 로직을 덮어씁니다.

플랫폼 매칭

플러그인은 각 ReleaseAsset의 구조화된 ParsedPlatform 데이터를 사용해 asset을 formula platform 항목과 매칭합니다. 기본 매칭 로직은 네 가지 플랫폼을 지원합니다.

Formula key	매칭 조건
`darwin-arm64`	`asset.platform.os === "darwin" && asset.platform.arch === "arm64"`
`darwin-x64`	`asset.platform.os === "darwin" && asset.platform.arch === "x64"`
`linux-arm64`	`asset.platform.os === "linux" && asset.platform.arch === "arm64"`
`linux-x64`	`asset.platform.os === "linux" && asset.platform.arch === "x64"`

이 방식은 asset 이름을 문자열로 매칭하던 이전 방식(예: asset.name.includes("darwin-arm64"))을 대체합니다. 이름이 바뀌어도 덜 깨집니다.

커스텀 플랫폼 매처

기본 os + arch 매칭이 충분하지 않을 때, 예를 들어 Linux에서 musl 빌드만 원할 때 assetPlatforms를 사용합니다.

brewTap({
  formula: "Formula/mytool.rb",
  assetPlatforms: {
    "darwin-arm64": (asset) =>
      asset.platform.os === "darwin" && asset.platform.arch === "arm64",
    "linux-x64": (asset) =>
      asset.platform.os === "linux" &&
      asset.platform.arch === "x64" &&
      asset.platform.abi === "musl",
  },
})

각 predicate는 ReleaseAsset를 받아, 해당 asset을 formula 항목에 사용해야 하면 true를 반환합니다.

자격 증명과 preflight check

@pubm/plugin-brew는 필요한 자격 증명과 check를 자체적으로 선언합니다. 별도로 수동 설정할 필요는 없습니다.

필수 자격 증명:

환경 변수	GitHub Secret 이름	용도
`PUBM_BREW_GITHUB_TOKEN`	`PUBM_BREW_GITHUB_TOKEN`	Homebrew formula 업데이트를 push하고 pull request를 열기 위한 `repo` 스코프의 GitHub Personal Access Token입니다.

로컬 실행에서는 pubm이 이 토큰을 프롬프트하고 시스템 keyring에 저장합니다. CI에서는 PUBM_BREW_GITHUB_TOKEN 환경 변수로 제공합니다. pubm --mode ci --phase prepare 또는 pubm secrets sync를 실행하면 저장된 토큰을 저장소의 GitHub Secrets로 동기화해 CI workflow가 바로 사용할 수 있게 됩니다.

이 플러그인은 또한 publish 단계가 시작되기 전에 토큰 존재 여부와 필요한 저장소 접근 권한을 검증하는 preflight check를 등록합니다.

동작

플러그인은 다음을 수행할 수 있습니다.

존재하지 않으면 formula 스캐폴드를 생성합니다.
구조화된 플랫폼 정보를 사용해 release asset의 url과 sha256을 갱신합니다.
formula 변경을 commit하고 push합니다.
직접 push가 적절하지 않으면 pull request 흐름으로 폴백합니다.

`brewCore`

기본 Homebrew 저장소인 homebrew-core에 기여할 때는 brewTap 대신 brewCore를 사용합니다.

import { brewCore } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewCore({
      formula: "Formula/my-tool.rb",
    }),
  ],
});

옵션	타입	설명
`formula`	`string`	저장소 루트 기준 formula 경로
`packageName`	`string`	모노레포용 선택적 package name 필터
`assetPlatforms`	`Record<string, (asset: ReleaseAsset) => boolean>`	선택적 커스텀 플랫폼 매처

brewCore는 homebrew/homebrew-core를 포크하고, formula를 업데이트한 뒤, PR을 자동으로 엽니다. brewTap과 마찬가지로 PUBM_BREW_GITHUB_TOKEN 자격 증명과 preflight check도 자동으로 선언합니다.

`@pubm/plugin-external-version-sync`

이 플러그인은 매니페스트가 아닌 파일을 패키지 버전에 맞춰 유지합니다. 버전 동기화 후 파이프라인이 실패하면 원본 파일 내용을 복원하는 롤백 액션을 등록합니다.

다음과 같은 파일을 릴리스와 함께 업데이트해야 할 때 사용합니다.

README.md의 설치 스니펫
docs 예제
앱 매니페스트
소스 상수
메타데이터 JSON 파일

일반적인 설정

import { defineConfig } from "@pubm/core";
import { externalVersionSync } from "@pubm/plugin-external-version-sync";

export default defineConfig({
  plugins: [
    externalVersionSync({
      targets: [
        {
          file: "src/constants.ts",
          pattern: /export const VERSION = "([^"]+)";/,
        },
        {
          file: "manifest.json",
          jsonPath: "metadata.version",
        },
        {
          file: "README.md",
          pattern: /pubm@([\\w.-]+)/,
        },
      ],
    }),
  ],
});

대상 타입

`regex`

임의의 텍스트 파일에 사용합니다.

{
  file: "README.md",
  pattern: /pubm@([\\w.-]+)/,
}

요구사항:

패턴은 정확히 하나의 capturing group으로 버전을 분리해야 합니다.
파일 형식은 안정적이어야 하며, 그래야 릴리스 자동화가 안전하게 업데이트할 수 있습니다.

`json`

기계가 읽을 수 있는 manifest에 사용합니다.

{
  file: "manifest.json",
  jsonPath: "metadata.version",
}

`pubm sync --discover`를 써야 할 때

저장소 어디에 version 문자열이 있는지 잘 모르겠다면 다음을 실행합니다.

pubm sync --discover

이 명령은 version 참조 후보를 스캔해, plugin config로 옮길 수 있는 후보 파일과 경로를 출력합니다.