#rlsbl.npm_wrapper

#rlsbl.npm_wrapper

Platform models and helpers for npm binary wrapper packages, providing job generation for publish workflows and scaffold template mappings.

#PlatformSpec

Partial platform descriptor (target-agnostic).

Contains only the npm/OS/CPU identifiers -- no archive or binary details, since those depend on the build target (Go, Rust, etc.).

#PlatformArtifact

Fully resolved platform artifact ready for package generation.

Combines platform identifiers with target-specific archive and binary information.

#NpmWrapperConfigError

Raised when npm_wrapper config carries a removed scoped-name key.

Scoped npm names (@scope/name) are banned by ecosystem policy, so the old scope/npm_scope activation keys were removed. The wrapper now activates via {"npm_wrapper": {"enabled": true}} and publishes bare per-platform names.

#npm_wrapper_enabled

def npm_wrapper_enabled(config: dict | None) -> bool

Return whether the npm binary-wrapper family is enabled for this config.

Activation is an explicit boolean gate: {"npm_wrapper": {"enabled": true}}.

Hard-errors (NpmWrapperConfigError) if the config carries the removed scope/npm_scope key, which used to activate scoped npm names (@scope/name). Scoped names are banned by ecosystem policy; the wrapper now publishes bare suffixed names like <bin>-linux-x64. Never silently ignore the old key -- an operator with a stale config must be told exactly why it stopped working.

#load_platform_config

def load_platform_config(config: dict) -> list[PlatformSpec]

Return platform specs, optionally filtered by config.

If config contains npm_wrapper.platforms (a list of npm_platform strings like ["linux-x64", "darwin-arm64"]), only matching entries from DEFAULT_PLATFORMS are returned. Otherwise all DEFAULT_PLATFORMS are returned.

#build_artifacts

def build_artifacts(specs: list[PlatformSpec], name: str, archive_fn: Callable[[PlatformSpec, str], tuple[str, str | None, str]]) -> list[PlatformArtifact]

Combine platform specs with target-specific archive details.

archive_fn(spec, name) must return a tuple of (asset_pattern, extract_cmd, binary_name) for each platform.

#build_npm_publish_jobs

def build_npm_publish_jobs(bin_command: str, artifacts: list[PlatformArtifact], depends_on: str='goreleaser', provenance: bool=False) -> str

Generate YAML for npm wrapper publish jobs in a publish workflow.

Returns a multi-line string injected at the jobs: level via the {{npmPublishJobs}} template variable in publish.yml.tpl.

artifacts provides the per-platform archive details (asset pattern, extract command, binary name) so this function is target-agnostic.

depends_on is the name of the job that must complete before npm-publish runs (e.g. "goreleaser" for Go, "build-and-upload" for Zig).

provenance threads --provenance into npm publish commands and adds id-token: write permission to the job (required for npm OIDC build-provenance attestation on GitHub Actions). Mirrors the id-token: write pattern.

#npm_wrapper_template_mappings

def npm_wrapper_template_mappings() -> list[dict[str, str]]

Return template mappings for npm wrapper shared templates.

Each mapping has "template" (relative to the shared template dir) and "target" (destination path in the project).