zhanghui d106a5c6ef
feat(plugins): add the everos-cloud-memory plugin and its host wiring (#883)
## Summary

Adds `everos-cloud-memory`, a separately distributed memory plugin for
EverOS Cloud, and wires the host so a second memory plugin is a
first-class choice.

The plugin (`plugins-dist/everos-cloud-memory`) is a thin REST client
over httpx: one API key (the config slice
`plugins.config.everos-cloud-memory.api_key`, or
`EVEROS_CLOUD_API_KEY`), owner ids from the host's `ServiceLocator`
(never from the slice), every add in `agent` mode, and a flush only when
a caller marks the conversation over (`metadata.flush` /
`metadata.is_final`: the sub-agent handoff and the importer's final
batch) and once at stop. It ships its own onboard screen (env or on-file
key used without a prompt; 401 / 403 / unreachable get their own
sentences with Re-enter or Skip), `delete` answers False (the cloud
deletes by scope, nothing calls it), and `health()` classifies seven
answers for `raven doctor` and the settings card.

Host changes, each guarded so `memory.backend` `everos` and `null`
behave exactly as before:

- `raven onboard` step 4 asks "Which memory backend?" when more than one
plugin contributes a screen (preselects the current backend, `Off`
clears it, cancel exits 1 and writes nothing); with one plugin the step
is byte-identical to today.
- The memory page reads whichever backend `memory.backend` names: the
cloud slice's key goes out as a Bearer header and the `/health` probe is
skipped for the cloud; a missing distribution is named in the page's
note.
- `settings.everos` reports `reason: "other_backend"` for any non-EverOS
backend, so the Model page hides the three EverOS-only roles (embedding
stays: knowledge bases use that pin); `settings.everosSet` refuses those
three sections for another backend; `settings.set` admits
`plugins.config.<id>.<field>` against the plugin's manifest through the
same admission door channels use; new `settings.everosCloud` feeds the
card (key source, endpoint, health).
- Provider-key and main-model saves no longer restart the local EverOS
when another backend is active.
- ui-web: an EverOS Cloud card (status chip, key row, endpoint) and the
`settings.everosCloud` data behind it. No page mounts the card: it drew
on Model settings until the owner ruled that a memory backend's endpoint
and credential answer neither question that page asks, and where it
belongs is the Memory section's to say once that section has a design.
Until then the key is entered through `raven onboard` or
`EVEROS_CLOUD_API_KEY`. The fixture gate pins the four optional fields
the offline library never sends.
- Gates: the plugin boundary test scans both memory plugins, coverage
and the release workflow build the second wheel, deptry's ignore list
names the plugin beside `raven_everos`, and a conftest fixture keeps the
second plugin out of entry-point discovery for the existing onboarding
tests (they describe a one-plugin install).

A second topic rides along, because it is what makes the hosted backend
reachable from an agent product at all. Every product under `agents/`
pinned its memory at the stock EverOS address and only `raven-design`
read the host's, so the other four addressed whatever answered on 18791
-- the wizard moves a managed server when the port is taken, and a
server the user runs themselves is wherever they put it.
`inherit_memory_backend` in `raven/config/product_render.py` now carries
`memory.backend`, the endpoint, and (only when the product holds none
itself) the credential from the host into every render, beside the host
denials and plugin opt-outs that already travel there; `raven-design`'s
private copy is deleted and the five product configs stop naming an
address. Identity never travels, which is what keeps five products apart
inside one store. `memory.backend: null` travels like any other value,
because that null is how an operator turns long-term memory off and a
product that kept writing would be the one surface ignoring them; the
product's own default stands only when the host carries no key at all.
Which store memories live in is not a product's choice either: the host
reads a sub-agent's memories back through its own backend, so a product
writing anywhere else left that record empty with nothing reporting it.
`owned` is forced off whenever the local backend is in force, because a
product infers ownership from a slice naming no root -- the shape all
five ship -- and so answered a host that was merely not serving by
starting a second server against a root of its own, stranding every
memory written so far.

Decisions worth a reviewer's eye: the fake cloud
(`tests/_everos_cloud_fake.py`) honours or refuses every field the
backend can send and serves both an in-process transport and an HTTP
face for the real-host acceptance; the live tests
(`tests/integration/test_everos_cloud_real_cloud.py`) skip without
`EVEROS_CLOUD_API_KEY`; run with a real key on 2026-10-09 all six pass
against api.evermind.ai (round trip, get by session, empty flush, 401
wording, probe with and without a key, and extraction without a flush
within two minutes), so the documentation and the service agree on
everything the plugin sends. Design, acceptance cases and plan are under
`docs/specs/2026-10-08-everos-cloud-memory-*.md` and `docs/plans/`.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

Rebased onto main `182dacac0` on 2026-10-13. What that rebase and the
four commits on top were verified with:

- Full suite, `uv run --frozen --python 3.12 --extra dev pytest -q` ->
**29748 passed, 8 failed** in 4m10s. All eight fail identically with
these four commits' sources reverted in-tree at the same base, so none
of them is this branch's: the two `test_the_products_tool_face_*` cases
in the code and oncall launchers (an extra `web_search` in the visible
tool set), `test_agent_loop_token_budget`,
`test_rpc_files::test_a_host_without_libreoffice_says_so`,
`test_ppt_engine_image_search`, `test_shell_background`, and the two
`test_simulation_*` cases.
- Real-host before and after for the inheritance, driving the launcher
the host spawns (`agents/raven-research/run.py`) against an isolated
`RAVEN_HOME` whose EverOS address is `19701`, not the stock port.
Before: the product rendered `base_url: http://localhost:18791` with no
`owned` key, ignored the host, and started an EverOS of its own -- an
orphaned `everos server start --root <its own state root>/everos`
holding 18791, which is the stranding this change exists to stop. After:
it rendered `{"base_url": "http://localhost:19701", "owned": false}` and
said so itself, "the EverOS you manage is not running at
http://localhost:19701 ... Raven does not start or stop it", with `ps`
and `lsof` confirming nothing was started. On the cloud the product
rendered `memory.backend: everos-cloud` with the host's key and left the
out-of-force local slice untouched, and `raven doctor` over that
rendered config answered `everos-cloud: ok https://api.evermind.ai`, so
the credential reached the service. Identity stayed `raven-research-ng`
throughout, and a fingerprint of the operator's own EverOS root was
identical before and after.
- The first CI round on this head found one that the local gates did
not: `tests/test_import_cycle_budget.py`. `inherit_memory_backend` read
the backend-to-distribution pairing from `raven.core.plugin_stack`, and
that edge from `raven.config` into `raven.core` -- which imports
`raven.config` back -- took mutual pairs from 13 to 14 and packages
inside a cycle from 18 to 22. `make lint-imports` keeps ten contracts
and none of them covers that pair, so it was green throughout. The
pairing now lives in `raven/config/raven.py` beside the two fields it
joins (`MemoryConfig.backend` names a contribution,
`PluginsConfig.config` is keyed by the distribution), which `raven.core`
may import and which imports nothing back; `plugin_stack` re-exports the
two names its own callers read from it. An intermediate commit put it in
`raven.contracts` instead, which broke the cycle but took the papers
ceiling from 3700 to 3719 lines -- `tests/test_kernel_budget.py` says a
new paper is a reviewed change to that ceiling, so it moved again rather
than raising it.
- The review round on this head raised one non-blocking finding, fixed
rather than carried forward: the inheritance read `memory.backend` with
`.get()`, which collapses an explicit `null` into an absent key, so a
host with long-term memory off left every packaged agent on its own
shipped backend and still writing. Reproduced by calling the function
directly before the change and after, now read on presence, and pinned
by a case whose mutation (restoring the `.get()`) turns it and nothing
else red.
- One ordering problem found while checking the above, pre-existing and
not fixed here: `tests/test_rpc_settings.py` run before
`tests/test_cli_onboard_commands.py` leaves
`raven.home._current_config_path` pointing at a dead tmp config, so the
onboard cases write somewhere else. With main's own copies of both files
and main's conftest in the tree it is 57 failures; with this branch's,
19. Which cases turn red changes run to run as xdist distributes them
differently.
- `cd ui-web && npx vitest run` -> 876 files, 3728 passed, 0 failed;
`npm run lint` -> 0 errors (4 warnings, all in files this change does
not touch); `npm run gen:check` -> in sync (228 methods); `npm run
type-check` -> clean; `cd ui-tui && npm run lint:i18n && npm run
lint:rpc` -> in sync
- `make lint-python` / `lint-imports` (10 contracts kept) / `lint-types`
/ `lint-deps` -> all pass; `uv lock --check` -> exit 0 with both sides'
new packages present; `scripts/check_source_language.py` and
`scripts/check_large_files.py` on `github/main..HEAD` -> exit 0;
commitlint over every commit -> ok
- Semantic-conflict audit of the rebase, beyond what the suite answers:
21 of the branch's 66 files are also in main's 499, and every one of
main's changes in them is additive and elsewhere in the file. The one
that could have broken silently is main's new `vision.model` /
`vision.provider` simple keys meeting this branch's new
`plugins.config.<id>.<field>` branch in `settings_set`; nothing in the
suite exercises `vision.*` through that method, so it was run directly
-> `{'applied': True}` and `{"model": "..."}` on disk. The subtraction
decisions were re-checked against the new base: no new caller of a
memory backend's `delete`, main's new onboard cases are about TLS and
not the memory step, `inherit_everos_address` exists nowhere, and
`DEFAULT_EVEROS_BASE_URL` is still defined.
- Mutation runs on the new code, restored afterwards: dropping `owned:
false`, letting the host's credential overwrite the product's own, not
writing the host's backend name, and carrying every memory slice instead
of the one in force each turn their own cases red; making the cloud card
render nothing turns 4 of its 5 new cases red and leaves the fifth
("draws nothing when not selected") green.

From the earlier round, on base `6d509a8c5`:

- `uv run --frozen --python 3.12 --extra dev pytest -p no:cacheprovider
-q tests/test_everos_cloud_fake.py tests/test_everos_cloud_backend.py
tests/test_everos_cloud_backend_contract.py
tests/test_everos_cloud_onboard.py tests/test_everos_cloud_discover.py
tests/test_cli_onboard_commands.py tests/test_rpc_memory.py
tests/test_rpc_settings.py tests/test_plugin_boundary.py
tests/test_rpc_schema_match.py tests/test_rpc_registration.py
tests/test_release_plugin_list.py
tests/integration/test_everos_cloud_real_cloud.py` -> 1001 passed, 6
skipped (the six live tests, no key)
- `cd ui-web && npx vitest run` -> 214 files, 3211 passed; `npm run
lint` -> 0 errors (4 warnings, all in files this change does not touch);
`npm run gen:check` -> in sync (207 methods); `cd ui-tui && npm run
lint:rpc && npm run lint:i18n` -> in sync
- `make lint` (ruff, ruff format, ui tsc, deptry) -> ok; `make
lint-types` -> All checks passed; `make build-ui` -> boot snapshots
match; `scripts/check_large_files.py` and
`scripts/check_source_language.py` on `6d509a8c5..HEAD` -> exit 0;
commitlint and `scripts/check_commit_messages.py` on each commit -> ok
- Mutation runs per change (restored afterwards, `git diff` clean): a
host import of the plugin turns the boundary test red; `import
raven_everos` in the plugin turns the import-isolation test red;
removing the chooser's cancel exit, the Bearer header, the restart
guard, the slice-admission guard, the Roles filter and the fake's two
fixes each turn their own test red
- Real-host acceptance (64 cases,
`docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`) run against a
fake EverOS Cloud: the wizard in tmux (chooser, key typed / from env /
on file, 401 / 403 / unreachable wording, back, Off, Ctrl-C,
non-interactive, base-tree transcript byte-identical with one plugin),
`raven agent` turns (user and agent-track recall, agent-mode adds, 4 s
recall bound, a 300 KB message dropped with a warning, a sub-agent trace
stored under its own ids, flushed and read back, one exit flush per
unflushed session), `raven import run` (3 adds then one flush; a hung
flush retried 4x and the exit sweep defeated), `raven doctor` under
seven cloud conditions (seven sentences, exit 2 only for the five
faults) and with the distribution hidden, and the web page through
playwright-cli (memory page counts and the fake's episode, empty and
refused stores, the Model page hiding the three EverOS-only roles while
the embedding row stays, the cloud card rotating a key and showing the
401 wording, three refused settings.set frames over the gateway
WebSocket, the local everos / null / mem0 backends drawing the page as
before, and a provider-key save that restarts the local EverOS on the
base tree and does not on this branch). Evidence and the per-case
verdicts are kept outside the repo. The live service was reached with a
real key after the acceptance run: six tests, six passes, the service's
replies archived with the evidence.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

User-visible changes: the wizard's step 4 chooser (only when two memory
plugins are installed); Model settings hides the three EverOS-only role
rows when `memory.backend` is not `everos`/`null` and draws no cloud
card; the memory page sends a Bearer header for the cloud backend.

Two behaviour changes for agent products, both on the `agents/` lane
only. An agent product now follows the host's `memory.backend` and
endpoint instead of its own, which is a fix for the four products that
never followed the host and a change for `raven-design`, which followed
the endpoint but not the backend. And a product no longer starts an
EverOS server of its own: where it used to answer a host that was not
serving by starting one against an empty root of its own, it now reports
long-term memory as unavailable, which is what the host does. Rollback
for this part is the one commit; the product configs it edits are
shipped files, not user config. The plugin is not installed by default
(its wheel is built by the release workflow; nothing changes for an
install without it). Rollback: revert the squash commit; the config
schema gains no new key (the slice is a plugin slice), so an older raven
reads a config written by this one.

Credentials: the cloud key is written only by `set_plugin_config_fields`
into the plugin's slice; the settings page's key row goes through
`settings.set` with a manifest-declared field, and
`settings.everosCloud` reports `api_key_set` / `key_source`, never the
value.

## Related Issues

N/A

---------

Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-14 11:08:11 +08:00

290 lines
15 KiB
YAML

# Release build — DRAFT.
#
# Goal: produce a wheel that ships a fresh, self-contained TUI bundle
# (ui-tui/dist/entry.js) so `pip`/`uv tool install` yields a working
# `raven tui` with no source checkout and no npm build on the user's machine.
#
# This is the "self-maintaining" piece: every tagged release rebuilds
# entry.js from the current ui-tui/ source, so the packaged TUI can never drift
# behind the Python code. Do NOT commit dist/entry.js to git — it is a build
# artifact produced here.
#
# Trigger: push a version tag (v1.2.3) or run manually.
name: release
on:
push:
tags:
- "v*"
workflow_dispatch: {}
concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false
jobs:
build-wheel:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v7
# 1) Node toolchain to build the TUI bundle.
- uses: actions/setup-node@v6
with:
node-version: "22"
# 2) Build the self-contained bundle into ui-tui/dist/entry.js.
# esbuild bundles react/ink in — no node_modules ships in the wheel.
- name: Build TUI bundle
working-directory: ui-tui
run: |
npm ci
npm run build
test -f dist/entry.js # fail fast if the bundle didn't land
# 2b) Build the served page into ui-web/dist. `ui-web/dist` is gitignored, so a
# fresh CI checkout has none and the wheel hook's else-branch fires
# its warning -- every tagged release would answer `/` with
# "No front end built here", which is the state this MR exists to end.
- name: Build the served page
run: |
npm ci --prefix ui-web
npm run --prefix ui-web build
python ui-web/build.py
test -f ui-web/dist/index.html # fail fast if the page didn't land
# 3) Build the wheel directly from the checkout so the freshly generated
# ui-tui/dist/entry.js is visible to Hatch's conditional build hook.
# Then build the sdist separately. A combined `uv build` first creates
# an sdist and then builds the wheel from that sdist, which drops this
# gitignored bundle before the wheel hook can include it.
- name: Install uv
uses: astral-sh/setup-uv@v8.2.0
# 2c) The template picker's covers. One cover is a LibreOffice conversion,
# and the gateway used to start ten of them a few seconds after every
# boot -- on hosts whose reader never opens the picker as much as on
# the ones that do. Rendered here instead, from the same templates the
# wheel carries, so an installed raven never runs LibreOffice to draw
# a picture it could have been given. `--extra dev` is what puts the
# engine (and PyMuPDF with it) in the environment the script imports.
- name: Bake the deck template covers
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends libreoffice-impress
uv run --frozen --extra dev python scripts/bake_deck_template_covers.py
- name: Build wheel + sdist
run: |
uv build --wheel
uv build --sdist
# The everos memory plugin ships as its own wheel from the same
# release; gh release create uploads everything under dist/.
uv build --wheel plugins-dist/everos-memory -o dist
uv build --wheel plugins-dist/everos-cloud-memory -o dist
# The product engines ship the same way. install.sh resolves them
# from the release assets by name, and the roster leaves
# Raven-Design and Raven-PPT disabled when they are not installed.
uv build --wheel plugins-dist/design-engine -o dist
uv build --wheel plugins-dist/ppt-engine -o dist
# 4) Sanity gate: the wheel MUST contain the bundle and MUST NOT carry
# node_modules or ui-tui sources (keeps the wheel lean and the smoke honest).
- name: Verify wheel contents
run: |
python3 - <<'PY'
import glob, sys, zipfile
whl = sorted(glob.glob("dist/raven-*.whl"))[-1]
names = zipfile.ZipFile(whl).namelist()
assert "raven/ui-tui/dist/entry.js" in names, "entry.js missing from wheel"
assert "raven/ui/dist/index.html" in names, "index.html missing from wheel"
# The half that degrades quietly: `resolve_ui_dist` accepts a dist with
# no assets, `build_app` skips mounting /assets, and the page loads
# with broken images rather than failing.
assert any(n.startswith("raven/ui/dist/assets/") for n in names), "page assets missing from wheel"
assert not any("node_modules" in n for n in names), "node_modules leaked into wheel"
# The only ui-tui/ entry must be the bundle — no TS source, no stray files.
ui = [n for n in names if "ui-tui/" in n]
assert ui == ["raven/ui-tui/dist/entry.js"], f"unexpected ui-tui entries: {ui}"
# The agent-product tree degrades the other way: an sdist-derived wheel
# has no folders at all, and onboarding step 5 reports an empty
# installation rather than failing.
agents = [n for n in names if n.endswith("/subagent.json")]
assert agents, "agent products missing from wheel"
# The tree is enumerated from git precisely so a built working copy's
# filled-in .env cannot ride along. Asserted at the publish boundary too.
leaked = [
n for n in names
if n.rsplit("/", 1)[-1].startswith(".env")
and not n.endswith((".example", ".sample", ".template"))
]
assert not leaked, f"secrets leaked into wheel: {leaked}"
print(f"OK: {whl} ships entry.js, the served page and {len(agents)} sub-agents, no node_modules")
PY
# 4a) The deck engine's own payload. The templates are tracked now, but
# a wheel that silently ships none is exactly the failure this gate
# exists to catch: `default_template_catalog()` returns an empty
# tuple and the deck agent degrades to "bring your own template"
# instead of failing, so nothing else notices.
- name: Verify ppt-engine wheel carries the bundled templates
run: |
python3 - <<'PY'
import glob, hashlib, json, zipfile
whl = sorted(glob.glob("dist/ppt_engine-*.whl"))[-1]
pins = json.load(open("plugins-dist/ppt-engine/templates.manifest.json"))["files"]
archive = zipfile.ZipFile(whl)
names = set(archive.namelist())
for entry in pins:
member = f"raven_ppt/assets/templates/{entry['name']}"
assert member in names, f"{entry['name']} missing from {whl}"
blob = archive.read(member)
assert len(blob) == entry["bytes"], f"{entry['name']} is {len(blob)} bytes, pinned {entry['bytes']}"
digest = hashlib.sha256(blob).hexdigest()
assert digest == entry["sha256"], f"{entry['name']} is {digest}, pinned {entry['sha256']}"
covers = [n for n in names if n.startswith("raven_ppt/assets/templates/covers/")]
# One per template per language, and the wheel is the only place they
# exist: the directory is gitignored, so a bake that did not run
# leaves a wheel that builds and installs and quietly puts LibreOffice
# back on every reader's machine.
langs = 1 + len(glob.glob("plugins-dist/ppt-engine/raven_ppt/assets/templates/i18n/*.json"))
assert len(covers) == len(pins) * langs, f"{len(covers)} covers in {whl}, expected {len(pins) * langs}"
print(f"OK: {whl} ships all {len(pins)} bundled templates, each matching its pin, and {len(covers)} covers")
PY
# 4b) Export the locked dependency set as a constraints file. The install
# scripts pass this to `uv tool install -c` so a one-click install gets
# the exact versions we lock and test, instead of re-resolving to the
# newest versions allowed by pyproject (which drifts, and can pull a
# source-only build with no wheel on the user's platform). --locked
# fails the release if uv.lock is stale vs pyproject, so we never ship
# constraints that conflict with the wheel's own metadata; --all-extras
# covers the channel SDKs behind raven[channels].
- name: Export locked constraints
run: uv export --locked --all-extras --no-hashes --no-emit-workspace -o dist/raven-constraints.txt
# 4c) The plugin list: the wheels this release ships beside raven, one
# `name @ url` line each. The upgrade helper (and, once it reads it,
# the installer) takes this file from the release directory next to
# the wheel and the constraints and hands it to `uv tool install
# --with-requirements`, so what a complete install is made of is
# written here once, from what this job just built, and nowhere
# else. Direct URLs on purpose: a bare name would be resolved against
# PyPI, where none of these names are ours. The everos line is what
# the helper keeps when the engines cannot build, so its name is a
# contract (tests/test_release_plugin_list.py).
- name: Write the plugin list
run: |
base="https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}"
: > dist/raven-plugins.txt
for whl in dist/everos_memory-*.whl dist/design_engine-*.whl dist/ppt_engine-*.whl; do
[ -f "$whl" ] || { echo "no wheel matches $whl"; exit 1; }
name="$(basename "$whl" | cut -d- -f1 | tr _ -)"
echo "$name @ $base/$(basename "$whl")" >> dist/raven-plugins.txt
done
cat dist/raven-plugins.txt
test "$(wc -l < dist/raven-plugins.txt)" -eq 3
# 4d) The release installs itself before anything is published: the wheel,
# the constraints, the plugin list and the plugin wheels as one whole,
# through install.sh piped the way users run it. The list's public URLs
# resolve only once a human publishes the draft, so the gate installs
# from a copy of the list rewritten to point at the release directory
# here; the rewrite only matches the exact public prefix, so a list
# that named any other place fails the grep below. Then the installed
# raven has to answer, carry the three plugin packages, and have the
# `web` the installer ends on.
- name: Install the release from dist with install.sh
env:
RAVEN_MINIMAL: "1"
RAVEN_NO_LAUNCH: "1"
UV_TOOL_DIR: ${{ runner.temp }}/gate/tools
UV_TOOL_BIN_DIR: ${{ runner.temp }}/gate/bin
UV_CACHE_DIR: ${{ runner.temp }}/gate/cache
RAVEN_HOME: ${{ runner.temp }}/gate/home
run: |
gate="$RUNNER_TEMP/gate/release"
mkdir -p "$gate"
cp dist/*.whl dist/raven-constraints.txt "$gate/"
prefix="https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/"
sed "s#$prefix#file://$gate/#" dist/raven-plugins.txt > "$gate/raven-plugins.txt"
if grep -q "https://" "$gate/raven-plugins.txt"; then echo "plugin list names a URL outside this release"; exit 1; fi
wheel="$(ls dist/raven-*-py3-none-any.whl)"
RAVEN_WHEEL_URL="file://$gate/$(basename "$wheel")" sh -c 'cat install.sh | sh'
"$UV_TOOL_BIN_DIR/raven" --version
"$UV_TOOL_DIR/raven/bin/python" -c "import raven_everos, raven_design, raven_ppt"
"$UV_TOOL_BIN_DIR/raven" web --help >/dev/null
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: dist
path: dist/*
# 5) On a version tag, publish a DRAFT GitHub Release with the built
# wheel + sdist attached. install.sh resolves the wheel from the
# latest Release asset, so a human reviews the draft and clicks
# Publish to make it live. Manual dispatch (no tag) stops after the
# artifact upload above.
- name: Check tag matches pyproject version
if: startsWith(github.ref, 'refs/tags/v')
run: |
tag="${{ github.ref_name }}"
v=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
base="${tag#v}"; base="${base%%-*}" # v0.1.3-rc1 -> 0.1.3
[ "$base" = "$v" ] || { echo "tag $tag does not match pyproject version $v"; exit 1; }
- name: Create draft GitHub Release with assets
if: startsWith(github.ref, 'refs/tags/v')
env:
GH_TOKEN: ${{ github.token }}
run: |
tag="${{ github.ref_name }}"
repo="${{ github.repository }}"
ver="${tag#v}"
today="$(date -u +%Y-%m-%d)"
# prerelease tags (contain a hyphen, e.g. v0.1.3-rc1) must never become
# /releases/latest, which install.sh serves to curl|sh users.
pre=""
case "$tag" in *-*) pre="--prerelease" ;; esac
# Prefill notes from the template; the summary and Highlights stay TODO
# for a human to fill in the draft before publishing.
sed "s/__VERSION__/$ver/g; s/__TAG__/$tag/g" \
.github/release-notes-template.md > "$RUNNER_TEMP/notes.md"
# Detect an existing release via the LIST endpoint: the tag endpoint is
# published-only and the Actions token cannot see a draft through it
# (cli/cli #3037), so a re-run would 422 on create. Delete a stale draft
# (this keeps the git tag) and recreate; leave a published release alone.
rel=$(gh api "repos/$repo/releases?per_page=100" --jq "map(select(.tag_name==\"$tag\"))[0] // {}")
id=$(printf '%s' "$rel" | jq -r '.id // empty')
isdraft=$(printf '%s' "$rel" | jq -r '.draft // false')
if [ -n "$id" ] && [ "$isdraft" = "true" ]; then
gh api -X DELETE "repos/$repo/releases/$id"
id=""
fi
if [ -z "$id" ]; then
draft_url=$(gh release create "$tag" dist/*.whl dist/*.tar.gz dist/raven-constraints.txt dist/raven-plugins.txt \
--title "Raven $ver ($today)" --notes-file "$RUNNER_TEMP/notes.md" --draft $pre)
# A draft lives at releases/tag/untagged-<hash> and keeps serving that
# stale page after publication, with no redirect to the real tag. Print
# both URLs so nobody shares the draft one by copying the address bar.
{
echo "### Release $tag"
echo ""
echo "- Draft (temporary, do not share): $draft_url"
echo "- Public URL once published: https://github.com/$repo/releases/tag/$tag"
} >> "$GITHUB_STEP_SUMMARY"
else
echo "Release $tag already published (id=$id); leaving as-is."
echo "Release $tag already published: https://github.com/$repo/releases/tag/$tag" >> "$GITHUB_STEP_SUMMARY"
fi
# (Optional, wire up when ready) publish to PyPI on tag:
# - name: Publish to PyPI
# if: startsWith(github.ref, 'refs/tags/v')
# run: uv publish
# env:
# UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}