Skip to content

feat(release): package firstmate for roca plugin install and update - #8

Merged
teseo merged 3 commits into
mainfrom
fm/roca-firstmate-releases
Aug 23, 2026
Merged

feat(release): package firstmate for roca plugin install and update#8
teseo merged 3 commits into
mainfrom
fm/roca-firstmate-releases

Conversation

@teseo

@teseo teseo commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

Intent

Give roca-firstmate a real release pipeline so operators can install and update the plugin through La Roca's supported path (roca plugin install / roca plugin update).

Until now that path could not work: there were no published releases, the git tree was not an installable package (checksums.txt covered only plugin.json), and an update of an existing custodial install failed with checksums.txt declares [plugin.json], want exactly [firstmate.db plugin.json].

This repository is also the normative example for third-party La Roca plugins, so the README has to walk an author through the shape: manifest, federated database and semantic fragment, verb dispatch via the plugin executable, custodial data, packaging and checksums, release flow, install and update, and semver.

What changed

  • Tag-driven GitHub Actions release for darwin-arm64 and linux-amd64. Each archive is a package-root .tar.gz with plugin.json, an empty custodial firstmate.db, the roca-firstmate executable, and checksums.txt covering exactly those three payload files. Versioned names and stable latest/download names are both published.
  • Packager (make package / make dist) generates the empty database at pack time. The git tree still does not commit a .db file. plugin.json is 0.5.0 with binary: roca-firstmate, so install places the executable in the plugin directory and on PATH (roca firstmate <verb>).
  • The checksum mismatch is a firstmate packaging defect, not a La Roca verifier bug. Declared databases are required package payload. Update preserves the installed custodial database.
  • README is the plugin-author example, including versioning: after a public release, changing the declared binary or the checksummed payload-file set is MAJOR. 0.5.0 is the first public installable package (0.4.0 was never published).
  • Git-sourced owner/repo installs cannot plugin update, because La Roca re-resolves the recorded source and the git tree is not an installable package. That is documented as a one-time cutover. The supported path is the release archive.

Out of scope and unchanged: plugin runtime behavior, La Roca product code, watcher design.

Testing

Scratch-home e2e against the installed La Roca plugin installer (never a live home):

check count
payload files in the package (manifest, db, executable, checksums) 4
N-1 to N update: custodial firstmate.db preserved 1
N-1 to N update: executable replaced 1
roca firstmate dispatch after install 1
fresh database on first use 1
data-only existing install: custodial db preserved, executable added 1
source with checksums covering only plugin.json rejected 1

make dist produced both platform archives. The workflow checksum-verification step accepted both: each archive contains exactly checksums.txt, firstmate.db, plugin.json, and roca-firstmate, and the checksums match.

Pipeline

Document step auto-fixed the versioning table so binary and payload-file changes are explicit MAJOR after a public release. Review, test, lint, and CI passed.

teseo added 3 commits August 23, 2026 21:10
Tag-driven CI ships darwin-arm64 and linux-amd64 archives with
plugin.json, empty firstmate.db, the executable, and matching
checksums. README is the normative plugin-author example.
@teseo
teseo merged commit df3014d into main Aug 23, 2026
1 check passed
@teseo
teseo deleted the fm/roca-firstmate-releases branch August 23, 2026 21:03
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