| name | lamprey-ship-and-release |
| description | How Lamprey runs and ships — run modes, userData layout, Windows release artifacts, the one-command "Bucket" pipeline, macOS/Linux CI mirroring, GitHub publication, CDN purge, and failure recovery. Load when the user says "ship", "release", "tag it", "Bucket", or when a release step fails partway. |
Lamprey Ship & Release
When to use / when not
- Use for any release/ship request, running the packaged app, understanding what lands where, or recovering a failed release step.
- Don't use for building/dev environment problems (see
lamprey-build-and-env) or the docs that must accompany a ship (see lamprey-docs-and-writing — the README update is mandatory, not optional).
Run modes
| Mode | Command | Notes |
|---|
| Dev | ELECTRON_EXEC_PATH=… npx electron-vite dev | see lamprey-build-and-env |
| Preview | npm run preview | serves the built bundle |
| Packaged | installed Lamprey-x64.exe or portable zip | single-instance lock: a second launch focuses the existing window |
| Headless CLI | --lamprey-headless argv (npm run lamprey) | exempt from the single-instance lock |
userData layout (%APPDATA%\Lamprey\ on Windows)
| Item | What | Safe to delete? |
|---|
lamprey.db (+ -wal/-shm) | all conversations/messages/loops/audit | No — that's the user's data |
keys.json | encrypted API keys | No (keys lost; .corrupt-* siblings are forensic copies) |
settings.json | app settings | Deleting resets to defaults |
tool-results/ | spilled tool outputs | Yes — GC'd automatically (age > 7 days, then oldest-first to a 256 MB cap) |
plugins/, skills/, slash-commands/, snip/filters/ | user + bootstrapped content | Deleting re-bootstraps bundled defaults on next launch |
backups/ | DB backups (encryption-aware) | Keep unless space-critical |
Release artifacts — the contract
npm run build:win (from the primary checkout, never a worktree) must produce in dist/:
Lamprey-x64.exe — NSIS installerLamprey-x64.exe.blockmap — delta-update manifestLamprey-x64.zip — portablelatest.yml — updater metadata (version + sha512)
Names are deliberately version-free so the CDN URLs (fronted by cdn.islandmountain.io) never change ("evergreen artifacts"). The version lives in the git tag, GitHub release, and latest.yml. Every ship must end with all four present in dist/ with fresh timestamps and latest.yml matching package.json version — verify this explicitly as the final step.
The Bucket pipeline (the canonical ship path)
When the user says "Bucket" (any variant), run from the repo root:
pwsh scripts\bucket.ps1 # flags: -NoBuild -NoTag -NoCrossPlatform -DryRun
What it does, in order:
- Builds
dist/ if latest.yml doesn't match package.json version.
- Tags + pushes
vX.Y.Z if the tag is missing.
- Uploads
Lamprey-x64.exe + Lamprey-x64.zip to the R2 bucket.
- Creates or updates the GitHub release with all four Windows artifacts and the
human release note at
RELEASE_NOTES/vX.Y.Z.md.
- Waits for the tag workflow, then mirrors
Lamprey-arm64.dmg and
Lamprey-x86_64.AppImage to R2.
- Purges the Cloudflare cache for every published CDN URL.
Lamprey has no iOS target or .ipa. The Apple artifact is a macOS DMG and must
not be described as an iOS build.
Preconditions:
- PowerShell 7 (
pwsh) — the script uses PS7-only syntax; Windows PowerShell 5.1 cannot parse it. If Get-Command pwsh fails: winget install --id Microsoft.PowerShell --silent.
- One-time setup:
pwsh scripts\bucket-setup.ps1 writes .bucket.json (R2 account/bucket/CDN/zone/repo), ~/.aws/credentials (R2 token), .cf/token — all gitignored. These persist across sessions; read the files, don't re-prompt the user for credentials.
- Run from the primary repo, not a worktree. Worktrees have no
node_modules; electron-builder fails with "Cannot compute electron version". From a worktree session: push the ship-arc to origin/main, fast-forward the primary (git -C <primary> pull --ff-only origin main), then Bucket from primary.
Failure recovery:
gh release create failing mid-upload with HTTP 404: check the release row,
the R2 objects, and the final Bucket summary before retrying. If only GitHub
failed, recover with one command carrying the four Windows artifacts:
gh release create vX.Y.Z dist/Lamprey-x64.exe dist/Lamprey-x64.exe.blockmap dist/Lamprey-x64.zip dist/latest.yml --title … --notes …
then delete any orphaned untagged-<hash> draft. R2 upload and CF purge are independent of the GH release — check whether they already succeeded before redoing them.
CI release paths (.github/workflows/build.yml)
- Tag push
v* → Windows, Linux, and macOS build jobs attach their artifacts to the tag release. Bucket creates the release row first and mirrors the two cross-platform packages after the workflow passes.
- Branch push to
main → same builds, but artifacts upload only as workflow artifacts (14-day retention), no release.
- All build jobs run both tsc configs +
smoke:bundle + smoke:renderer. macOS builds unsigned (CSC_IDENTITY_AUTO_DISCOVERY: 'false').
Ship-completion checklist
- Version bumped in
package.json; full gate green (npm run verify:proof, both smokes, npm test).
- DEVLOG phase/release entry written; CLAUDE.md current-state updated (formats:
lamprey-docs-and-writing).
- README.md updated — download heading/URLs, "New in vX.Y.Z" paragraph, Quick start link, Roadmap top entry. This is a standing rule on every release, without exception.
pwsh scripts\bucket.ps1 (or tag + gh release create for a manual path).- Final verification: four Windows artifacts in
dist/ with fresh timestamps;
latest.yml matches; GitHub shows Windows, macOS, and Linux packages; all four
downloadable packages are present in R2 and served by the CDN after purge.
Push policy still applies (lamprey-change-control): a ship instruction from the user authorizes the pushes it requires; don't ask again mid-flow.
Code signing status (2026-07-02)
Builds are unsigned; the updater verifies sha512 from latest.yml only. When an Authenticode cert is acquired (owner action), setting WIN_CSC_LINK + WIN_CSC_KEY_PASSWORD enables signing with no code changes (electron-builder.yml is pre-wired).
Provenance and maintenance
Based on reads of scripts/bucket.ps1, scripts/bucket-setup.ps1, electron-builder.yml, .github/workflows/build.yml, and CLAUDE.md ship rules, at v0.20.0 (2026-07-18).
Re-verify:
- Pipeline steps/flags:
head -60 scripts/bucket.ps1
- Artifact names:
grep -n "artifactName\|productName" electron-builder.yml
- CI paths:
grep -n "tags:\|startsWith" .github/workflows/build.yml
- pwsh present:
pwsh -v
Authored and reviewed by Basho Parks, copyright 2026
