From 3bdfdd26468f8eba83b59edf4feb06cf2b8042e4 Mon Sep 17 00:00:00 2001 From: Logan Johnson Date: Sun, 1 Mar 2026 21:54:31 -0500 Subject: [PATCH 1/2] feat(penpal): add release tooling recipes and update README Add changelog, prepare, and release justfile recipes for repeatable version bumping and release workflows. Update README with Homebrew as primary install method and build-from-source for development. Co-Authored-By: Claude Opus 4.6 --- apps/penpal/README.md | 36 ++++++++++++++++------------ apps/penpal/justfile | 56 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+), 15 deletions(-) diff --git a/apps/penpal/README.md b/apps/penpal/README.md index 34f4be19..6a0fdbaf 100644 --- a/apps/penpal/README.md +++ b/apps/penpal/README.md @@ -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 @@ -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 diff --git a/apps/penpal/justfile b/apps/penpal/justfile index 5d99139d..ff30c5be 100644 --- a/apps/penpal/justfile +++ b/apps/penpal/justfile @@ -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 -- apps/penpal/) + else + COMMITS=$(git log --oneline -- apps/penpal/) + 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 apps/penpal/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 apps/penpal/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 # ============================================================================ From 9fa7182f6322c2abab256c0277e69d09047749d9 Mon Sep 17 00:00:00 2001 From: Logan Johnson Date: Sun, 1 Mar 2026 22:00:25 -0500 Subject: [PATCH 2/2] fix(penpal): correct CWD-relative paths in release recipes The justfile runs from apps/penpal/ so pathspecs and file references need to be relative to that directory, not the repo root. Co-Authored-By: Claude Opus 4.6 --- apps/penpal/justfile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/apps/penpal/justfile b/apps/penpal/justfile index ff30c5be..ce0ecbd7 100644 --- a/apps/penpal/justfile +++ b/apps/penpal/justfile @@ -134,9 +134,9 @@ changelog version: 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 -- apps/penpal/) + COMMITS=$(git log --oneline "$LAST_TAG"..HEAD -- .) else - COMMITS=$(git log --oneline -- apps/penpal/) + COMMITS=$(git log --oneline -- .) fi if [ -z "$COMMITS" ]; then @@ -145,9 +145,9 @@ changelog version: fi echo "$COMMITS" | claude -p --dangerously-skip-permissions \ - "These are commits since the last release. Prepend a new changelog section to apps/penpal/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." + "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 apps/penpal/CHANGELOG.md + penpal open CHANGELOG.md read -p "Press enter when done editing changelog..." # Bump version and generate changelog for review