Skip to content

feat(ci): publish plugin SDK to crates.io as a renamed chain#95

Draft
raphaelvigee wants to merge 1 commit into
masterfrom
feat/publish-plugin-sdk-to-crates-io
Draft

feat(ci): publish plugin SDK to crates.io as a renamed chain#95
raphaelvigee wants to merge 1 commit into
masterfrom
feat/publish-plugin-sdk-to-crates-io

Conversation

@raphaelvigee

Copy link
Copy Markdown
Member

What

Makes plugin-sdk — the transport-agnostic Provider/Driver author surface — publishable to crates.io so third-party developers can write their own heph plugins.

Why the renamed-chain approach

crates.io cannot vendor path deps; every dependency must resolve from the registry. A single self-contained crate (true "vendoring") is blocked by htspec-derive, a proc-macro that is part of the public API — authors apply #[derive(Spec)] / SpecEnum to their own config structs (see plugin-go/driver_*.rs), so it must run at the author's build and cannot be pre-expanded or merged into a lib crate.

So the closure ships as a renamed heph-* chain (the bare names core/model/plugin are taken/reserved on crates.io).

Surface reduction

  • Dropped the dead walk dependency from plugin — only the crate's own fn walk method matched the grep; WalkEntry/WalkEntryKind come from hcore::hartifactcontent. Removing it drops the rusqlite/r2d2/wax/glob/borsh tail off the publish surface entirely.

Publish set (topological): heph-core, heph-model, heph-htspec-derive, heph-proto-gen, heph-plugin, heph-driver-support, heph-plugin-abi, heph-plugin-stabby, heph-plugin-sdk.

How

  • scripts/publish/ — stages the publish set into an isolated virtual workspace (sidesteps rewriting non-publish members), rewrites manifests (rename → heph-*, inject version + crates.io metadata, add version reqs to intra-set path deps), validates with cargo metadata, then publishes in dependency order. cargo publish blocks on the index between crates so each dependent resolves.
  • .github/workflows/publish-crates.yml — tag pushes (v*) publish for real; manual dispatch defaults to a dry run that compiles the full renamed chain. (Per-crate --dry-run can only validate leaves, since a dependent's heph-* deps aren't on the registry yet; the real sequential publish works because each crate hits the index before the next builds.)
  • Requires a CRATES_IO_TOKEN repo secret.

Licensing

Repo and published crates licensed AGPL-3.0-only; adds LICENSE.md (verbatim AGPL-3.0 text) and license/repository on the root manifest.

Validation

  • walk removal: plugin, plugin-sdk, and the full stabby tier build clean.
  • ./scripts/publish/publish-crates.sh <ver> --dry-run stages, rewrites, and compiles the renamed chain end-to-end locally; leaf crates also pass cargo publish --dry-run (packaging incl. generated proto sources confirmed).

🤖 Generated with Claude Code

Third-party plugin authors integrate against `plugin-sdk` (the transport-
agnostic Provider/Driver author surface). To make it consumable, ship it and
its dependency closure to crates.io.

crates.io cannot vendor path deps, and a single-crate flatten is blocked by the
`htspec-derive` proc-macro (it's public API — authors derive `Spec`/`SpecEnum`
on their own config types, so it must run in the author's build). So publish the
closure as a renamed `heph-*` chain (the bare names core/model/plugin are
taken/reserved).

- Drop the dead `walk` dependency from `plugin` (only the crate's own `fn walk`
  matched; `WalkEntry` comes from `hcore::hartifactcontent`). Removes the
  rusqlite/r2d2/wax tail from the publish surface.
- scripts/publish: stage the publish set into an isolated virtual workspace,
  rewrite manifests (rename -> heph-*, inject version + crates.io metadata, add
  version reqs to intra-set path deps), then publish in topological order.
- .github/workflows/publish-crates.yml: tag pushes publish; manual dispatch
  defaults to a dry run (compiles the renamed chain; uploads are exercised only
  on a real sequential publish, since each crate must reach the index before the
  next resolves).
- License the repo and the published crates under AGPL-3.0-only; add LICENSE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@raphaelvigee raphaelvigee marked this pull request as draft June 18, 2026 22:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant