feat(plugin): install via release wheel URLs by gbrlcustodio · Pull Request #260 · pipefy/ai-toolkit

gbrlcustodio · 2026-06-01T00:31:31Z

Summary

Switches .mcp.json and commands/install.md from uvx --from git+...@latest#subdirectory=... to direct GitHub Release wheel URLs. Eliminates the full git clone + setuptools build pass that every plugin install or --refresh paid per workspace member (sdk, auth, infra, mcp).
Adds a step to .github/workflows/release.yml that, after creating the GitHub Release, patches .mcp.json, commands/install.md, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json on main to point at the just-cut tag's wheels, and commits the result.
Updates README MCP-client wiring blocks (Cursor, Claude Desktop, Codex) to show the same wheel-URL shape with <TAG> and <VERSION> placeholders. Curl installer (install: one-command curl installer (CLI + MCP + skills + client config) #231) is the path that resolves these automatically once it ships.

Design notes

PEP 491 compliance. Wheel filenames stay in canonical pipefy_<pkg>-<version>-py3-none-any.whl form. No renamed-stable copies. URLs are version-pinned, and the workflow rewrites them per release.
pipefy-infra is an explicit --with. uvx will not auto-resolve a workspace-only transitive dep from PyPI pre-v1.
README intentionally not patched by the workflow. Three reasons: dev/main divergence would create per-release merge conflicts, copy-pasting from non-main branches would surface stale URLs, and the README install blocks are documentation rather than a programmatic install path. Placeholders + the curl installer (install: one-command curl installer (CLI + MCP + skills + client config) #231) cover the user-facing path.
Branch protection on main is currently off (gh api repos/.../branches/main/protection → 404), so the workflow can push directly. If branch protection lands later, swap the push for a gh pr create fallback.

Test plan

python3 -c "ver='0.2.0-beta.2'; print(ver.replace('-beta.', 'b').replace('-rc.', 'rc').replace('-alpha.', 'a'))" returns 0.2.0b2. Same derivation handles -rc., -alpha., plain 1.0.0.
.mcp.json parses as valid JSON.
release.yml parses as valid YAML.
uv run pytest passes (2916 passed, 46 skipped).
After this lands on dev and v0.2.0-beta.2 ships, smoke claude plugin install pipefy@pipefy and /pipefy:install — both should resolve via releases/download/... URLs with no git clone.

Out of scope

CLI ad-hoc / permanent install blocks in README (lines 158–176). Same git+#subdirectory= form. Separate follow-up.
docs/setup.md (deleted in [Unreleased]; issue text was stale).

Release sequencing

This is step 1 of the v0.2.0-beta.2 release train. Bump PR (chore/release-v0.2.0-beta.2 → dev) follows, then the dev → main release PR.

- release.yml: serialize tag-push runs (concurrency group), validate tag→PEP-440 normalization against an allowlist instead of silent passthrough, and fail the patch step if `.mcp.json` has zero URL matches (catches a silent no-op when main's URL shape drifts). - README.md: scope the `@latest` / `--with #subdirectory=` claims to the snippets that still use them; describe /pipefy:install as the curl-installer delegate it now is. - packages/mcp/README.md: fix dead "Quick install" cross-reference. - CHANGELOG.md: describe the wiring blocks as duplicated across both READMEs (they weren't moved — b8069bd reverted the move).

adriannoes

Solid release-train step: wheel URLs drop the git-clone cost, the workflow guards (PEP 440 allowlist, n == 0, concurrency, git checkout $GITHUB_SHA) look thoughtful, and CI plus a local unit run (2916 passed) are green. One inline on /pipefy:install — everything else is coordination notes for the train you already documented.

Also noted

F2 — .mcp.json pins v0.2.0-beta.2 before the tag exists: Replacing git+@latest with hard-coded release URLs will 404 for the Claude Code plugin on dev until the tag ships and assets upload. Fine as infrastructure-only step 1; just don't smoke-test the plugin on dev between merge and release.
F3 — CHANGELOG wording: The Unreleased bullet says paste-into-config wheel blocks landed in both READMEs, but only packages/mcp/README.md got the new subsection after the root README revert — worth tightening so release notes match the diff.

@latest

Switch `.mcp.json` and `commands/install.md` from `uvx --from git+...@latest#subdirectory=...` to direct GitHub Release wheel URLs. Eliminates the full git clone + setuptools build pass that every plugin install or `--refresh` previously paid per workspace member (sdk, auth, infra, mcp). The release workflow gains a step that, after creating the GitHub Release, patches `.mcp.json`, `commands/install.md`, `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` on `main` to point at the just-cut tag's wheels and commits the result. README MCP-client wiring blocks (Cursor, Claude Desktop, Codex) show the same wheel-URL shape with `<TAG>` and `<VERSION>` placeholders; the curl installer (#231) will resolve them automatically once it ships. Closes #234.

- Drop the `if: startsWith(github.ref_name, 'v')` guard on the new manifest-patch step. The workflow trigger is already `tags: ["v*"]`, so the conditional was always true. - Restructure the empty-diff check as `if !; else` so the no-op path doesn't `exit 0` early. The new `git checkout ${GITHUB_SHA}` line needs to run on both branches. - After pushing to main, `git checkout ${GITHUB_SHA}` so the working tree is back at the tag commit. Subsequent steps (Stage PyPI / Smoke / Upload) use untracked dist/ paths and are unaffected today, but a future step that reads tracked files would otherwise silently see main's tip instead of the tag. - Document the PEP 440 normalization's scope inline. - Alphabetize the package list in `commands/install.md`'s description frontmatter.

- release.yml: serialize tag-push runs (concurrency group), validate tag→PEP-440 normalization against an allowlist instead of silent passthrough, and fail the patch step if `.mcp.json` has zero URL matches (catches a silent no-op when main's URL shape drifts). - README.md: scope the `@latest` / `--with #subdirectory=` claims to the snippets that still use them; describe /pipefy:install as the curl-installer delegate it now is. - packages/mcp/README.md: fix dead "Quick install" cross-reference. - CHANGELOG.md: describe the wiring blocks as duplicated across both READMEs (they weren't moved — b8069bd reverted the move).

adriannoes

Solid release-train step: wheel URLs drop the git-clone cost on every plugin install/refresh, and the release workflow guards (PEP 440 allowlist, n == 0, concurrency, git checkout $GITHUB_SHA) are thoughtful. Review included a local checkout of head 4f22047 — uv run pytest -m "not integration" (2955 passed) and ruff check green; CI on the PR is green.

The earlier /pipefy:install → main/install.sh thread is resolved (#269); v0.2.0-beta.2 wheels are on the release, so the forward-pinned .mcp.json is fine to merge.

Also noted

CHANGELOG: Unreleased bullet claims wiring blocks in both READMEs; only packages/mcp/README.md changed — inline on CHANGELOG.md.
root README: Line 91 still describes /pipefy:install as uv tool install; this PR's commands/install.md delegates to install.sh — inline on commands/install.md with a nudge to update root README.md.

After merge: smoke claude plugin install pipefy@pipefy and /pipefy:install against the pinned wheels.

…h delegation

…s at pipefy/ai-toolkit #271 (org rename) landed in main while this branch carried the release-wheel work. Resolved .mcp.json and commands/install.md to keep the wheel-URL and install.sh-delegation behavior from this branch, and repointed the new paste-into-config wheel URLs in packages/mcp/README.md (added here, so they auto-merged still on the old org) to pipefy/ai-toolkit.

adriannoes assigned gbrlcustodio Jun 1, 2026

gbrlcustodio added this to the v0.2.0-beta.2 milestone Jun 1, 2026

gbrlcustodio requested review from Danielmoraisg and adriannoes and removed request for adriannoes June 1, 2026 23:05

adriannoes reviewed Jun 2, 2026

View reviewed changes

Comment thread commands/install.md Outdated

Base automatically changed from dev to main June 2, 2026 14:39

gbrlcustodio added 4 commits June 2, 2026 11:52

feat(plugin): delegate /pipefy:install to curl installer

6134877

gbrlcustodio force-pushed the feat/234-release-wheel-urls branch from e3dd7e5 to 4f22047 Compare June 2, 2026 14:53

gbrlcustodio requested a review from adriannoes June 2, 2026 14:59

adriannoes approved these changes Jun 2, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

Comment thread commands/install.md Outdated

This was referenced Jun 2, 2026

feat(install): register Claude Code MCP server at user scope #270

Draft

chore(140): repoint github URLs at pipefy/ai-toolkit #271

Merged

Rename to ai-toolkit and transfer to the Pipefy GitHub org #140

Closed

gbrlcustodio added 3 commits June 2, 2026 16:18

fix(pr-review): scope changelog wheel-block note to packages/mcp/README

a47f418

fix(pr-review): align root README /pipefy:install note with install.s…

270e7db

…h delegation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(plugin): install via release wheel URLs#260

feat(plugin): install via release wheel URLs#260
gbrlcustodio wants to merge 7 commits into
mainfrom
feat/234-release-wheel-urls

gbrlcustodio commented Jun 1, 2026

Uh oh!

adriannoes left a comment •

edited

Loading

Uh oh!

Uh oh!

adriannoes left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

gbrlcustodio commented Jun 1, 2026

Summary

Design notes

Test plan

Out of scope

Release sequencing

Uh oh!

adriannoes left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Also noted

Uh oh!

Uh oh!

adriannoes left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Also noted

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adriannoes left a comment •

edited

Loading

adriannoes left a comment •

edited

Loading