Skip to content

chore: release v2.6.0 — plugin-release.yml releases archetype bundles too - #66

Merged
mabry1985 merged 2 commits into
mainfrom
feat/archetype-bundle-release
Oct 12, 2026
Merged

mabry1985 merged 2 commits into
mainfrom
feat/archetype-bundle-release

Conversation

@mabry1985

Copy link
Copy Markdown
Member

Why

Archetype repos (protoagent.bundle.yaml, no protoagent.plugin.yaml) have no path through the fleet release ritual: plugin-release.yml greps version: out of protoagent.plugin.yaml only. Every archetype release so far (engineer-archetype v0.1.0–v0.1.3, analyst-archetype v0.1.0–v0.1.1, project-manager-archetype ≤ v0.6.0, brand-launch-archetype v0.1.0) was hand-cut with gh release create, with no themed notes and no Discord post. Two are waiting now: project-manager-archetype v0.7.0 and brand-launch-archetype v0.2.0.

What

  • Manifest auto-detect. protoagent.plugin.yaml wins if present (plugin, behaviour unchanged). Otherwise protoagent.bundle.yaml is used (archetype). A new optional manifest input can override it. Callers need no change. They keep @v2.
  • Version guard. A missing or non-semver version: now fails the run with an error. Before, it tagged a bare v. The grep is pipefail-safe, and quotes and trailing comments are stripped.
  • Archetype labelling.
    • Discord embed title is Archetype · <repo> vX.Y.Z, with footer protoLabs · archetype · <repo>.
    • The GitHub release body opens with a one-line archetype note.
    • Plugin releases pass empty strings, which keeps the action's existing defaults.
  • action.yml gets a title input that maps to RELEASE_NOTES_TITLE. The npm 2.4.1 notes generator that npx …@latest resolves to already honours that variable.
  • README: documents bundles and adds the fork guard to the caller example.
  • Bumps to 2.6.0. The squash subject chore: release v2.6.0 fires release.yml, which tags v2.6.0 and moves the v2 alias. That is how callers pick this up.

Bundle schema check

protoAgent's graph/plugins/bundles.py::load_bundle only requires id and plugins. Unknown top-level keys are ignored, so adding version: to a bundle is inert for the installer. The update check resolves newer semver tags via ls-remote, so the tag remains the version of record. version: only feeds the tag.

Testing

  • I extracted the resolve step and ran it under bash -eo pipefail against five repos:
    • plugin + bundle both present → plugin v0.5.0
    • bundle only → archetype v0.7.0
    • bundle with no version: → explicit error
    • quoted version with a trailing comment → v0.2.0
    • neither manifest → explicit error
  • zizmor@1.25.2 --min-severity=medium on plugin-release.yml reports the same findings before and after: the pre-existing artipacked and unpinned-uses findings. Nothing new.

Known follow-up (unchanged by this PR)

npm publish is still failing (ENEEDAUTH, #62), so release.yml will tag v2.6.0 and move v2, then stop at the npm step, the same way v2.5.0 did. Consumers resolve the workflow and action from git @v2, so they are unaffected.

🤖 Generated with Claude Code

… too

The reusable plugin-release.yml read `version:` only from
protoagent.plugin.yaml, so archetype (bundle) repos had no release path
and were hand-cut with `gh release create` — no themed notes, no Discord.

- Auto-detect the manifest: protoagent.plugin.yaml (plugin) if present,
  else protoagent.bundle.yaml (archetype). New optional `manifest` input
  overrides it. Existing plugin callers are unchanged.
- Fail loudly on a missing/non-semver `version:` instead of tagging `v`
  (pipefail-safe grep). Quotes and trailing comments are stripped.
- Archetype releases say so: Discord embed title `Archetype · <repo> vX`,
  footer `protoLabs · archetype · <repo>`, and a leading archetype line
  in the GitHub release body.
- action.yml: new `title` input (RELEASE_NOTES_TITLE, already honoured
  by the notes generator on npm 2.4.1).
- README documents bundles and the fork guard in the caller example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA panel review — WARN

code-review-structural · head d83ec13863ad · formal

Overall risk is low. The verifier confirmed the concurrency TOCTOU race (the one fix-first item: add a concurrency key to the release job) and the missing main/exports entry point, but refuted the PREV-SHA finding — the release-notes action uses git log ranges where a raw SHA is perfectly valid. The Windows-glob nit is marked uncertain: Node 20+ --test may handle globs natively, making the shell-expansion premise moot, but this is unverified. No panel disagreement; all four findings came from the protoPatch engine and the verifier settled each on its own evidence. No coverage gaps to flag.

Findings

Severity Location Finding Verified
🟡 minor .github/workflows/plugin-release.yml:95 No concurrency guard allows duplicate tag/release creation on rapid re-triggers. confirmed
⚪ nit package.json:25 Published lib/ directory has no package entry point (no main or exports field). confirmed · nearby, not gating
⚪ nit package.json:41 Test script uses shell glob that fails on Windows. ⚠️ uncertain · nearby, not gating
findings JSON (machine-readable)
[
  {
    "file": ".github/workflows/plugin-release.yml",
    "line": 95,
    "severity": "minor",
    "category": "concurrency",
    "claim": "No concurrency guard allows duplicate tag/release creation on rapid re-triggers.",
    "evidence": "The workflow checks whether the tag already exists (line 95\u2013100) and gates subsequent steps on `exists == 'false'`. However, there is no `concurrency` key on the job or workflow. If two `workflow_dispatch` events (or a `workflow_dispatch` and a push matching the commit-message pattern) fire close together, both runs can check out before either has pushed the tag, both see `exists=false`, and both proceed to create the tag and release.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Read the full workflow at head SHA d83ec13: no `concurrency` key exists at workflow or job level. The check (`git rev-parse \"$TAG\"`) and the tag creation (`git tag` + `git push`) are in separate steps with no mutual exclusion \u2014 a classic TOCTOU race."
  },
  {
    "file": "package.json",
    "line": 25,
    "severity": "nit",
    "category": "conventions",
    "claim": "Published lib/ directory has no package entry point (no `main` or `exports` field).",
    "evidence": "The `files` array includes `lib/` (line 27), which means library code is published to npm. However, the package defines neither a `main` nor an `exports` field. External consumers who `import` or `require` this package will receive a confusing module-resolution error.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Read full package.json (46 lines) at head SHA: no `main` or `exports` key present. `files` includes `\"lib/\"` (line 27). Pre-existing condition (PR only bumps version), but the factual claim is accurate. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": "package.json",
    "line": 41,
    "severity": "nit",
    "category": "conventions",
    "claim": "Test script uses shell glob that fails on Windows.",
    "evidence": "The script `node --test test/*.mjs` relies on shell glob expansion of `*`. On Windows (cmd or PowerShell), the `*` is not expanded, so Node receives the literal string `test/*.mjs` and fails to find any test files.",
    "source": "protopatch",
    "verdict": "uncertain",
    "note": "The script is confirmed at line 41. However, Node.js 20+ `--test` supports glob patterns natively (the test runner expands them internally), so the Windows shell may not need to expand `*`. Cannot confirm or refute without running on Windows; the claim's premise (shell must expand) may be wrong for Node \u226520. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  }
]

2 structural finding(s) are nearby notes, not part of the verdict: they sit in code this PR did not change (outside its changed lines and the functions those lines are in). Worth a look; not a request for this PR.

  • package.json:25 (nit) — Published lib/ directory has no package entry point (no main or exports field).
  • package.json:41 (nit) — Test script uses shell glob that fails on Windows.

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Promoting the WARN verdict for head d83ec13863ad: all checks terminal-green, zero unresolved review threads. (approve-on-green)

Open findings carried by this approval — non-blocking, but they did not go away:

  • minor .github/workflows/plugin-release.yml:95 — No concurrency guard allows duplicate tag/release creation on rapid re-triggers.
  • nit package.json:25 — Published lib/ directory has no package entry point (no main or exports field).
  • nit package.json:41 — Test script uses shell glob that fails on Windows.

Approving a WARN does not resolve its findings (issue #22).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA panel review — WARN

code-review-structural · head 3c6f948ac540 · formal

Low-risk change. The single surviving finding is a minor operational concern: a partial failure between git push and gh release create can leave an orphan tag that the idempotency check then treats as "already done." The verifier confirmed the finding at head 3c6f948, verifying the exact line references and the absence of any release-object check in the workflow. No panel disagreement; all four LLM finders independently found zero defects, and the one tool-sourced finding (protopatch) was the only item to survive. No coverage gaps — the verifier's annotation count matches the synthesized findings exactly.

Findings

Severity Location Finding Verified
🟡 minor .github/workflows/plugin-release.yml:110 Partial-failure leaves orphan tag with no GitHub release on retry: steps 4 (lines 110–119) perform git tag, git push, then gh release create as three sequentia… confirmed
findings JSON (machine-readable)
[
  {
    "file": ".github/workflows/plugin-release.yml",
    "line": 110,
    "severity": "minor",
    "category": "build-release",
    "claim": "Partial-failure leaves orphan tag with no GitHub release on retry: steps 4 (lines 110\u2013119) perform git tag, git push, then gh release create as three sequential non-transactional operations. If git push succeeds but gh release create fails (transient API error, rate limit, network blip), the tag exists on the remote but no release is created. On the next run, the idempotency check on line 102 (git rev-parse \"$TAG\") finds the tag in fetched refs and skips release creation.",
    "evidence": "The idempotency guard at line 102 checks only for tag existence (git rev-parse), not for a corresponding GitHub release object. A tag without a release is indistinguishable from a completed release to the guard. Fix: before declaring exists=true, verify a GitHub release object exists (e.g., gh release view \"$TAG\" --json url); if the tag exists but the release does not, proceed to create the release.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Re-read at head 3c6f948: line 102 is `if git rev-parse \"$TAG\" >/dev/null 2>&1; then` (tag-only check); lines 115\u2013119 are `git tag` \u2192 `git push origin` \u2192 `gh release create` in one run block. A push-then-release-create failure leaves the tag on the remote; the next run's checkout (fetch-depth: 0) fetches it, rev-parse succeeds, exists=true, and the release step is skipped. No release-object check exists anywhere in the workflow."
  }
]

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Promoting the WARN verdict for head 3c6f948ac540: all checks terminal-green, zero unresolved review threads. (approve-on-green)

Open findings carried by this approval — non-blocking, but they did not go away:

  • minor .github/workflows/plugin-release.yml:110 — Partial-failure leaves orphan tag with no GitHub release on retry: steps 4 (lines 110–119) perform git tag, git push, then gh release create as three sequential non-transactional operations. If git pu

Approving a WARN does not resolve its findings (issue #22).

@mabry1985

Copy link
Copy Markdown
Member Author

Triage:

  • Round 1: I fixed the concurrency TOCTOU in 3c6f948, with a per-repo concurrency group that queues runs and does not cancel them. The two package.json nits are pre-existing and nearby, so I've left them.
  • Round 2: the orphan-tag-on-partial-failure finding is real but pre-existing. This PR doesn't change the tag, push, and release-create sequence or the tag-only idempotency check. It's a follow-up: gate exists on gh release view, not just git rev-parse. I'm merging on the approved WARN.

@mabry1985
mabry1985 merged commit 1bdbc3d into main Oct 12, 2026
3 checks passed
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