Skip to content

feat(penpal): add release tooling and update README #321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
loganj merged 2 commits into from
Mar 2, 2026
+77 −15
Merged

feat(penpal): add release tooling and update README #321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3bdfdd2
feat(penpal): add release tooling recipes and update README
loganj Mar 2, 2026
9fa7182
fix(penpal): correct CWD-relative paths in release recipes
loganj Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 21 additions & 15 deletions apps/penpal/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,30 +16,26 @@ A desktop app and local web server that **only** operates on markdown files insi
- **MCP server** at `/mcp` for AI agents to participate in document review programmatically
- **Agent presence** -- shows when an agent is actively monitoring a file

## Quick Start
## Install

### Prerequisites
### Homebrew (recommended)

**just** - Command runner ([install guide](https://github.com/casey/just))
```bash
brew install just
brew install --cask block/tap/penpal
```

Building requires Go, Node.js, and Rust.
On first launch, Penpal will prompt you to install the CLI and Claude Code plugin.

### Develop
### Build from source

```bash
just dev # Desktop app with Vite HMR + Go sidecar
```

### Install
For development, you can build and install locally. Requires Go, Node.js, Rust, and [just](https://github.com/casey/just).

```bash
just install # Build .app, copy to /Applications, install Claude Code plugin
just uninstall # Remove .app and Claude Code plugin
just install # Build dev-branded .app and copy to /Applications
```

Dev builds show "Penpal Dev" in the menu bar so you can distinguish them from Homebrew installs.

### CLI

```bash
Expand All @@ -52,12 +48,22 @@ penpal open thoughts/shared/plans/my-doc.md # Open file in Penpal desktop app
|---|---|
| `just dev` | Desktop app with Vite HMR + Go sidecar |
| `just build` | Build sidecar + frontend + desktop `.app` bundle |
| `just build-sidecar` | Build Go sidecar binaries for desktop app |
| `just build-go` | Build Go sidecar binaries for desktop app |
| `just package` | Build + zip `.app` for distribution |
| `just test` | Run all tests (Go + React) |
| `just test-e2e` | Playwright end-to-end tests |
| `just check` | Format Go code + tidy dependencies |
| `just fmt` | Format Go code |
| `just clean` | Remove build artifacts |

### Releasing

```bash
just prepare 0.2.0 # Bump version, generate changelog for review
just release 0.2.0 # Commit, tag, push → CI builds and publishes
```

`just prepare` updates the version in `Cargo.toml` and `package.json`, generates a changelog entry using Claude, and opens it in Penpal for review. `just release` commits the version bump, creates a `penpal/v*` tag, and pushes to trigger the CI release pipeline.

### Server options

```bash
Expand Down
56 changes: 56 additions & 0 deletions apps/penpal/justfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,62 @@ test: ensure-deps
# Verify everything without modifying files — for CI
ci: ensure-deps fmt-check lint typecheck test

# ============================================================================
# Release
# ============================================================================

# Generate changelog entry for a release version
changelog version:
#!/usr/bin/env bash
set -euo pipefail

LAST_TAG=$(git describe --tags --match "penpal/v*" --abbrev=0 2>/dev/null || echo "")
if [ -n "$LAST_TAG" ]; then
COMMITS=$(git log --oneline "$LAST_TAG"..HEAD -- .)
else
COMMITS=$(git log --oneline -- .)
fi

if [ -z "$COMMITS" ]; then
echo "No commits found since last release."
exit 1
fi

echo "$COMMITS" | claude -p --dangerously-skip-permissions \
"These are commits since the last release. Prepend a new changelog section to CHANGELOG.md using v{{version}} as the heading. Group changes by theme and write human-readable descriptions, not raw commit messages. Match the existing style."

penpal open CHANGELOG.md
read -p "Press enter when done editing changelog..."

# Bump version and generate changelog for review
prepare version:
#!/usr/bin/env bash
set -euo pipefail

# Update version in Cargo.toml (source of truth)
sed -i '' 's/^version = ".*"/version = "{{version}}"/' frontend/src-tauri/Cargo.toml
# Update version in package.json
cd frontend && npm version "{{version}}" --no-git-tag-version && cd ..

# Generate and review changelog
just changelog {{version}}

echo ""
echo "Version bumped to {{version}} and changelog updated."
echo "Review the changes, then run 'just release {{version}}' to ship."

# Commit, tag, and push to trigger the release build
release version:
#!/usr/bin/env bash
set -euo pipefail

git add frontend/src-tauri/Cargo.toml frontend/package.json CHANGELOG.md
git commit -m "release: penpal v{{version}}"
git tag "penpal/v{{version}}"
git push origin main "penpal/v{{version}}"

echo "Pushed penpal/v{{version}} — CI will build and publish the release."

# ============================================================================
# Other
# ============================================================================
Expand Down