From 936760d68f92705480208d419e988472197fbaf7 Mon Sep 17 00:00:00 2001 From: Walter Cheng Date: Sun, 26 Jul 2026 14:15:10 -0400 Subject: [PATCH] feat: publish release contents to an npm registry The generic archive and its installer are opaque to coding agents: something external has to download and unpack them, which is why the generated installer script exists. Agents can resolve npm packages on their own, so publishing the same release contents to an npm registry lets them install and update without an installer in the loop. Opt in with `publish_npm`. The package is built from the same staged directory as the generic archive, so the two cannot drift, and `package.json` is generated with the release version so it stays in step with the plugin manifest versions that release-please already bumps. Two npm behaviours are handled explicitly: - `npm pack ` without a leading `./` is parsed as a GitHub owner/repo spec, so npm attempts a clone instead of packing the directory. - npm's ignore rules can drop dot-directories, and the agent catalogs live in `.agents/` and `.claude-plugin/`. The packed tarball is verified to contain every released path before publishing, rather than shipping a package that installs but has no catalog. The generic archive, installer, and GitHub Release paths are unchanged, so existing consumers are unaffected. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jm9AfbCJBD4tkxnxxnq7Wm --- .../workflows/agent-marketplace-release.yaml | 127 ++++++++++++++++++ README.md | 32 +++++ 2 files changed, 159 insertions(+) diff --git a/.github/workflows/agent-marketplace-release.yaml b/.github/workflows/agent-marketplace-release.yaml index c3a6e38..05ba511 100644 --- a/.github/workflows/agent-marketplace-release.yaml +++ b/.github/workflows/agent-marketplace-release.yaml @@ -98,6 +98,28 @@ on: required: false type: string default: "" + publish_npm: + description: >- + Publish the release contents as an npm package so agents that support npm + marketplace catalogs can install and auto-update from the registry. + required: false + type: boolean + default: false + npm_package_name: + description: >- + Scoped npm package name, for example `@acme/agent-skills`. The scope must + match the registry owner. Required when publish_npm is enabled. + required: false + type: string + default: "" + npm_registry: + description: >- + npm registry base URL, for example + `https://gitea.example.com/api/packages/acme/npm/`. Defaults to the Gitea + npm registry for gitea_user when gitea_url is set. + required: false + type: string + default: "" secrets: GITHUB_PAT: description: Optional GitHub token for release-please pull requests. @@ -105,6 +127,11 @@ on: GITEA_TOKEN: description: Gitea token with permission to publish generic packages. required: false + NPM_TOKEN: + description: >- + Token for the npm registry. Falls back to GITEA_TOKEN when unset, which + covers publishing to a Gitea npm registry. + required: false permissions: contents: write @@ -166,6 +193,93 @@ jobs: done tar -czf "dist/${ARCHIVE_NAME}-${VERSION}.tar.gz" -C dist "${dir}" + - name: Set up Node + if: inputs.publish_npm + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Publish npm package + if: inputs.publish_npm + id: npm + env: + ARCHIVE_NAME: ${{ inputs.archive_name }} + GITEA_URL: ${{ inputs.gitea_url }} + GITEA_USER: ${{ inputs.gitea_user }} + NPM_PACKAGE_NAME: ${{ inputs.npm_package_name }} + NPM_REGISTRY: ${{ inputs.npm_registry }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN || secrets.GITEA_TOKEN }} + PACKAGE_PATHS: ${{ inputs.package_paths }} + VERSION: ${{ needs.release-please.outputs.version }} + shell: bash + run: | + set -euo pipefail + : "${NPM_PACKAGE_NAME:?Set npm_package_name when publish_npm is enabled}" + : "${NPM_TOKEN:?Pass NPM_TOKEN or GITEA_TOKEN when publish_npm is enabled}" + + registry="${NPM_REGISTRY}" + if [[ -z "$registry" ]]; then + : "${GITEA_URL:?Set npm_registry, or gitea_url and gitea_user, when publish_npm is enabled}" + : "${GITEA_USER:?Set npm_registry, or gitea_url and gitea_user, when publish_npm is enabled}" + registry="${GITEA_URL%/}/api/packages/${GITEA_USER}/npm/" + fi + [[ "$registry" == */ ]] || registry="${registry}/" + + scope="${NPM_PACKAGE_NAME%%/*}" + if [[ "$scope" != @* ]]; then + echo "npm_package_name must be scoped (for example @acme/agent-skills) so the registry mapping is unambiguous" >&2 + exit 1 + fi + + # The staged directory already holds exactly the released content, so the npm + # package and the generic archive can never drift apart. + pkg_dir="dist/${ARCHIVE_NAME}-${VERSION}" + files_json="$(printf '%s\n' ${PACKAGE_PATHS} | jq -R . | jq -s .)" + jq -n \ + --arg name "$NPM_PACKAGE_NAME" \ + --arg version "$VERSION" \ + --argjson files "$files_json" \ + '{name: $name, version: $version, files: $files, private: false}' \ + > "${pkg_dir}/package.json" + + # `npm pack ` without a leading `./` is parsed as a GitHub owner/repo + # spec, so npm tries to clone it instead of packing the directory. + tarball_name="$(npm pack --pack-destination dist "./${pkg_dir}")" + : "${tarball_name:?npm pack did not produce a tarball}" + tarball="dist/${tarball_name}" + + # npm's default ignore rules have historically surprised people with + # dot-directories, and the agent catalogs live in `.agents/` and + # `.claude-plugin/`. Fail here rather than shipping an unusable package. + contents="$(tar -tzf "$tarball")" + missing=0 + for path in ${PACKAGE_PATHS}; do + [[ -e "$path" ]] || continue + if ! grep -q "^package/${path}" <<<"$contents"; then + echo "npm package is missing released path: ${path}" >&2 + missing=1 + fi + done + if [[ "$missing" -ne 0 ]]; then + echo "Refusing to publish an npm package that does not match the release archive." >&2 + exit 1 + fi + + registry_auth="${registry#https://}" + registry_auth="${registry_auth#http://}" + { + printf '%s:registry=%s\n' "$scope" "$registry" + printf '//%s:_authToken=%s\n' "$registry_auth" "$NPM_TOKEN" + } > "$HOME/.npmrc" + trap 'rm -f "$HOME/.npmrc"' EXIT + + npm publish "./${tarball}" --registry "$registry" + # Keep the packed tarball out of the GitHub Release upload glob. + rm -f "$tarball" + + echo "npm_package=${NPM_PACKAGE_NAME}" >> "$GITHUB_OUTPUT" + echo "npm_registry=${registry}" >> "$GITHUB_OUTPUT" + - name: Build Gitea installers if: inputs.publish_gitea env: @@ -363,11 +477,24 @@ jobs: CODEX_MARKETPLACE_NAME: ${{ inputs.codex_marketplace_name }} CURSOR_PLUGIN_NAME: ${{ inputs.cursor_plugin_name }} GITEA_INSTALLER_URL: ${{ steps.gitea.outputs.installer_url }} + NPM_PACKAGE: ${{ steps.npm.outputs.npm_package }} + NPM_REGISTRY_URL: ${{ steps.npm.outputs.npm_registry }} run: | { printf '# Agent plugin %s\n\n' "$VERSION" printf 'Release tag: `%s`\n\n' "$TAG" + if [[ -n "$NPM_PACKAGE" ]]; then + printf '## npm registry\n\n' + printf 'Published `%s@%s` to `%s`.\n\n' "$NPM_PACKAGE" "$VERSION" "$NPM_REGISTRY_URL" + printf 'Agents that support npm marketplace catalogs can install this package ' + printf 'directly and pick up later releases without re-running an installer. ' + printf 'Authenticate first if the registry is private:\n\n' + printf '%s\n' '```bash' + printf 'npm config set %s:registry %s\n' "${NPM_PACKAGE%%/*}" "$NPM_REGISTRY_URL" + printf '%s\n\n' '```' + fi + if [[ -n "$GITEA_INSTALLER_URL" ]]; then printf '## Claude Code\n\n' printf '%s\n' '```bash' diff --git a/README.md b/README.md index da629a3..2176d03 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ This repository intentionally contains only generic marketplace automation: - skill and plugin manifest validation - pull-request preview archives - release archives and installation summaries +- optional npm registry publishing for agents that support npm catalogs Container, infrastructure, deployment, and environment-specific workflows are kept in the private `Walter0697/common-workflow` repository. @@ -28,3 +29,34 @@ The validator is also available as: ```yaml uses: walter-base/common-workflow/actions/validate-agent-marketplace@master ``` + +## Publishing to an npm registry + +The generic archive and its installer are opaque to coding agents: something has +to download and unpack them, which is what the generated installer script does. +Agents can, however, resolve npm packages on their own, so publishing the same +release contents to an npm registry lets them install and update without an +installer. + +Enable it on the release workflow: + +```yaml +with: + publish_npm: true + npm_package_name: "@acme/agent-skills" + # npm_registry defaults to the Gitea npm registry for gitea_user +secrets: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} +``` + +Notes: + +- the package is built from the same staged directory as the generic archive, so + the two can never drift apart +- `package.json` is generated at publish time with the release version, which + keeps it in step with the plugin manifest versions that release-please bumps +- `npm_package_name` must be scoped, and the scope must match the registry owner +- `NPM_TOKEN` is used when set; otherwise `GITEA_TOKEN` is reused +- publishing fails if any released path is absent from the packed tarball, which + guards against npm's ignore rules silently dropping `.agents/` or + `.claude-plugin/`