From e8fb384ae1ad850f4db1809e94a6ba2cb37b0924 Mon Sep 17 00:00:00 2001 From: Logan Lindquist Land Date: Sun, 21 Jun 2026 09:24:51 -0500 Subject: [PATCH 1/3] ci: publish Homebrew-compatible release artifacts (tarballs + checksums) ### Features - Add `build:linux-arm64` script to package.json and matrix target in auto-release.yml - Rename each Unix binary to `upkeep` before archiving, then tar+gzip as `upkeep___.tar.gz` using `amd64`/`arm64` tokens - Generate `checksums.txt` (SHA-256) over all tarballs - Upload tarballs, checksums.txt, and Windows .exe as release artifacts Closes #7 --- .github/workflows/auto-release.yml | 45 ++++++++++++++++++++++-------- package.json | 3 +- 2 files changed, 35 insertions(+), 13 deletions(-) diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml index e4fd949..109c281 100644 --- a/.github/workflows/auto-release.yml +++ b/.github/workflows/auto-release.yml @@ -90,6 +90,9 @@ jobs: - target: linux-x64 os: ubuntu-latest artifact: upkeep-linux-x64 + - target: linux-arm64 + os: ubuntu-latest + artifact: upkeep-linux-arm64 - target: darwin-arm64 os: macos-latest artifact: upkeep-darwin-arm64 @@ -141,17 +144,36 @@ jobs: with: path: artifacts - - name: Prepare release files + - name: Package release archives + env: + VERSION: ${{ needs.version.outputs.version }} run: | mkdir -p release - cp artifacts/upkeep-linux-x64/upkeep-linux-x64 release/ - cp artifacts/upkeep-darwin-arm64/upkeep-darwin-arm64 release/ - cp artifacts/upkeep-darwin-x64/upkeep-darwin-x64 release/ - cp artifacts/upkeep-windows-x64.exe/upkeep-windows-x64.exe release/ - chmod +x release/upkeep-linux-x64 - chmod +x release/upkeep-darwin-arm64 - chmod +x release/upkeep-darwin-x64 + + # Tar+gzip each Unix binary as `upkeep` inside the archive, named + # upkeep___.tar.gz with Homebrew-style arch tokens. + archive() { + src="$1"; os="$2"; arch="$3" + cp "$src" upkeep + chmod +x upkeep + tar -czf "release/upkeep_${VERSION}_${os}_${arch}.tar.gz" upkeep + rm upkeep + } + archive artifacts/upkeep-linux-x64/upkeep-linux-x64 linux amd64 + archive artifacts/upkeep-linux-arm64/upkeep-linux-arm64 linux arm64 + archive artifacts/upkeep-darwin-x64/upkeep-darwin-x64 darwin amd64 + archive artifacts/upkeep-darwin-arm64/upkeep-darwin-arm64 darwin arm64 + + # Windows ships as a raw .exe — Homebrew does not consume it. + cp artifacts/upkeep-windows-x64.exe/upkeep-windows-x64.exe \ + "release/upkeep_${VERSION}_windows_amd64.exe" + + # checksums.txt lists the sha256 of each tarball; the Homebrew tap + # downloads this to render per-platform url + sha256. + ( cd release && sha256sum upkeep_"${VERSION}"_*.tar.gz > checksums.txt ) + ls -la release/ + cat release/checksums.txt - name: Generate changelog uses: orhun/git-cliff-action@v4 @@ -167,10 +189,9 @@ jobs: with: tag_name: ${{ needs.version.outputs.tag }} files: | - release/upkeep-linux-x64 - release/upkeep-darwin-arm64 - release/upkeep-darwin-x64 - release/upkeep-windows-x64.exe + release/*.tar.gz + release/*.exe + release/checksums.txt body: ${{ steps.changelog.outputs.content }} draft: false prerelease: false diff --git a/package.json b/package.json index a8888aa..101d868 100644 --- a/package.json +++ b/package.json @@ -10,8 +10,9 @@ "scripts": { "dev": "bun run src/cli/index.ts", "build": "bun build ./src/cli/index.ts --compile --outfile dist/upkeep", - "build:all": "bun run build:linux-x64 && bun run build:darwin-arm64 && bun run build:darwin-x64 && bun run build:windows-x64", + "build:all": "bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:darwin-arm64 && bun run build:darwin-x64 && bun run build:windows-x64", "build:linux-x64": "bun build ./src/cli/index.ts --compile --target=bun-linux-x64 --outfile dist/upkeep-linux-x64", + "build:linux-arm64": "bun build ./src/cli/index.ts --compile --target=bun-linux-arm64 --outfile dist/upkeep-linux-arm64", "build:darwin-arm64": "bun build ./src/cli/index.ts --compile --target=bun-darwin-arm64 --outfile dist/upkeep-darwin-arm64", "build:darwin-x64": "bun build ./src/cli/index.ts --compile --target=bun-darwin-x64 --outfile dist/upkeep-darwin-x64", "build:windows-x64": "bun build ./src/cli/index.ts --compile --target=bun-windows-x64 --outfile dist/upkeep-windows-x64.exe", From e4481616747244af7bf124bcbad60e7fee21802b Mon Sep 17 00:00:00 2001 From: Logan Lindquist Land Date: Sun, 21 Jun 2026 09:25:09 -0500 Subject: [PATCH 2/3] docs: call upkeep from PATH in skills, document brew install ### Documentation - Replace `./bin/upkeep` invocations with `upkeep` (PATH-based) in upkeep-audit, upkeep-deps, and upkeep-quality skills - Document `brew install llbbl/tap/upkeep` as the recommended prerequisite in each skill's prerequisites section - Add graceful "upkeep not found on PATH" guard with actionable error message Closes #8 --- skills/upkeep-audit/SKILL.md | 37 +++++++++++++++++++----------- skills/upkeep-deps/SKILL.md | 41 +++++++++++++++++++++------------- skills/upkeep-quality/SKILL.md | 31 ++++++++++++++++--------- 3 files changed, 71 insertions(+), 38 deletions(-) diff --git a/skills/upkeep-audit/SKILL.md b/skills/upkeep-audit/SKILL.md index e56ae19..70551bd 100644 --- a/skills/upkeep-audit/SKILL.md +++ b/skills/upkeep-audit/SKILL.md @@ -46,14 +46,25 @@ This skill helps you: ## Prerequisites -- `./bin/upkeep` binary must be available in this skill's directory +- The `upkeep` binary must be installed and available on your `PATH`. Install it with: + ```bash + brew install llbbl/tap/upkeep + ``` + (or download a binary from the [GitHub releases](https://github.com/llbbl/upkeep/releases)). +- Before running any `upkeep` command, verify it is on `PATH` and stop with a clear message if not: + ```bash + command -v upkeep >/dev/null 2>&1 || { + echo "upkeep not found on PATH — install it with: brew install llbbl/tap/upkeep" >&2 + exit 1 + } + ``` ## Workflow ### Step 1: Run Security Audit ```bash -./bin/upkeep audit --json +upkeep audit --json ``` This returns vulnerabilities with: @@ -82,7 +93,7 @@ For each vulnerability, explain: For each fixable vulnerability: ```bash -./bin/upkeep risk --from --to --json +upkeep risk --from --to --json ``` This helps understand: @@ -102,11 +113,11 @@ This helps understand: **For transitive dependencies:** The fix often requires updating a parent dependency. Check which direct dependency pulls in the vulnerable package and update that instead. -Use `./bin/upkeep imports ` to understand the impact. +Use `upkeep imports ` to understand the impact. ### Step 5: Verify Fixes -1. Re-run audit: `./bin/upkeep audit --json` +1. Re-run audit: `upkeep audit --json` 2. Run tests: ` test` 3. Check for regressions @@ -122,8 +133,8 @@ Some vulnerabilities may not have fixes yet. Options: User: "Check my project for security issues" -1. Run `./bin/upkeep detect --json` to understand the project -2. Run `./bin/upkeep audit --json` to scan for vulnerabilities +1. Run `upkeep detect --json` to understand the project +2. Run `upkeep audit --json` to scan for vulnerabilities 3. Present findings grouped by severity 4. For each fixable vulnerability: - Explain the issue @@ -146,11 +157,11 @@ User: "Check my project for security issues" | Command | Purpose | |---------|---------| -| `./bin/upkeep audit` | Run security audit | -| `./bin/upkeep detect` | Detect package manager | -| `./bin/upkeep risk ` | Assess upgrade risk | -| `./bin/upkeep imports ` | Find package usage | -| `./bin/upkeep deps` | List all outdated packages | +| `upkeep audit` | Run security audit | +| `upkeep detect` | Detect package manager | +| `upkeep risk ` | Assess upgrade risk | +| `upkeep imports ` | Find package usage | +| `upkeep deps` | List all outdated packages | ## Handling Common Scenarios @@ -169,7 +180,7 @@ Lower priority since it doesn't affect production. Still fix if: ### Breaking Change Required for Fix -1. Assess impact with `./bin/upkeep risk` +1. Assess impact with `upkeep risk` 2. Check migration guides 3. Consider if the security risk outweighs the migration effort 4. For critical vulns, usually worth the effort diff --git a/skills/upkeep-deps/SKILL.md b/skills/upkeep-deps/SKILL.md index 45a2202..b002bf9 100644 --- a/skills/upkeep-deps/SKILL.md +++ b/skills/upkeep-deps/SKILL.md @@ -45,7 +45,18 @@ This skill helps you upgrade dependencies safely by: ## Prerequisites -- `./bin/upkeep` binary must be available in this skill's directory +- The `upkeep` binary must be installed and available on your `PATH`. Install it with: + ```bash + brew install llbbl/tap/upkeep + ``` + (or download a binary from the [GitHub releases](https://github.com/llbbl/upkeep/releases)). +- Before running any `upkeep` command, verify it is on `PATH` and stop with a clear message if not: + ```bash + command -v upkeep >/dev/null 2>&1 || { + echo "upkeep not found on PATH — install it with: brew install llbbl/tap/upkeep" >&2 + exit 1 + } + ``` - `gh` CLI for Dependabot PR integration (optional but recommended) ## Workflow @@ -53,7 +64,7 @@ This skill helps you upgrade dependencies safely by: ### Step 1: Detect Project Configuration ```bash -./bin/upkeep detect --json +upkeep detect --json ``` This tells you: @@ -64,7 +75,7 @@ This tells you: ### Step 2: Check for Dependabot PRs (if gh CLI available) ```bash -./bin/upkeep dependabot --json +upkeep dependabot --json ``` Dependabot PRs are pre-tested and often the safest to merge first. @@ -72,7 +83,7 @@ Dependabot PRs are pre-tested and often the safest to merge first. ### Step 3: Get Outdated Packages ```bash -./bin/upkeep deps --json +upkeep deps --json ``` This returns all outdated packages categorized by update type (major/minor/patch). @@ -81,7 +92,7 @@ This returns all outdated packages categorized by update type (major/minor/patch Present upgrades to the user in this priority order: 1. **Dependabot PRs** - Already have PRs ready, checks may be passing -2. **Security fixes** - Check `./bin/upkeep audit --json` for vulnerabilities +2. **Security fixes** - Check `upkeep audit --json` for vulnerabilities 3. **Patch updates** - Lowest risk, bug fixes only 4. **Minor updates** - New features, should be backward compatible 5. **Major updates** - Breaking changes, highest risk @@ -91,7 +102,7 @@ Present upgrades to the user in this priority order: Before upgrading, assess the risk: ```bash -./bin/upkeep risk --json +upkeep risk --json ``` This analyzes: @@ -136,9 +147,9 @@ For major upgrades, use explicit version: User: "Update my dependencies" -1. Run `./bin/upkeep detect --json` to understand the project -2. Run `./bin/upkeep deps --json` to see what's outdated -3. Run `./bin/upkeep audit --json` to check for security issues +1. Run `upkeep detect --json` to understand the project +2. Run `upkeep deps --json` to see what's outdated +3. Run `upkeep audit --json` to check for security issues 4. Present a prioritized list to the user 5. For approved upgrades, run risk assessment and execute 6. Test after each upgrade @@ -161,9 +172,9 @@ Only do this if: | Command | Purpose | |---------|---------| -| `./bin/upkeep detect` | Detect project configuration | -| `./bin/upkeep deps` | List outdated packages | -| `./bin/upkeep audit` | Security vulnerability scan | -| `./bin/upkeep imports ` | Find where package is used | -| `./bin/upkeep risk ` | Assess upgrade risk | -| `./bin/upkeep dependabot` | List Dependabot PRs | +| `upkeep detect` | Detect project configuration | +| `upkeep deps` | List outdated packages | +| `upkeep audit` | Security vulnerability scan | +| `upkeep imports ` | Find where package is used | +| `upkeep risk ` | Assess upgrade risk | +| `upkeep dependabot` | List Dependabot PRs | diff --git a/skills/upkeep-quality/SKILL.md b/skills/upkeep-quality/SKILL.md index 7277d31..05f7bf0 100644 --- a/skills/upkeep-quality/SKILL.md +++ b/skills/upkeep-quality/SKILL.md @@ -45,7 +45,18 @@ This skill helps you: ## Prerequisites -- `./bin/upkeep` binary must be available in this skill's directory +- The `upkeep` binary must be installed and available on your `PATH`. Install it with: + ```bash + brew install llbbl/tap/upkeep + ``` + (or download a binary from the [GitHub releases](https://github.com/llbbl/upkeep/releases)). +- Before running any `upkeep` command, verify it is on `PATH` and stop with a clear message if not: + ```bash + command -v upkeep >/dev/null 2>&1 || { + echo "upkeep not found on PATH — install it with: brew install llbbl/tap/upkeep" >&2 + exit 1 + } + ``` ## Quality Metrics @@ -75,7 +86,7 @@ The quality score is calculated from 6 weighted metrics: ### Step 1: Generate Quality Report ```bash -./bin/upkeep quality --json +upkeep quality --json ``` This returns: @@ -125,7 +136,7 @@ Many issues can be fixed automatically: User: "How healthy is my project?" -1. Run `./bin/upkeep quality --json` +1. Run `upkeep quality --json` 2. Present the grade and score prominently 3. Show the breakdown chart 4. Highlight areas needing attention @@ -138,7 +149,7 @@ User: "How healthy is my project?" ```bash # Check outdated packages -./bin/upkeep deps --json +upkeep deps --json # Update all patch versions (usually safe) update @@ -148,7 +159,7 @@ User: "How healthy is my project?" ```bash # Find vulnerabilities -./bin/upkeep audit --json +upkeep audit --json # Fix what's available audit fix # npm @@ -206,15 +217,15 @@ Consider adding `knip` or `ts-prune` for advanced detection. | Command | Purpose | |---------|---------| -| `./bin/upkeep quality` | Generate quality report | -| `./bin/upkeep detect` | Check project configuration | -| `./bin/upkeep deps` | Dependency freshness details | -| `./bin/upkeep audit` | Security details | +| `upkeep quality` | Generate quality report | +| `upkeep detect` | Check project configuration | +| `upkeep deps` | Dependency freshness details | +| `upkeep audit` | Security details | ## Tracking Progress After making improvements: -1. Re-run `./bin/upkeep quality --json` +1. Re-run `upkeep quality --json` 2. Compare new score to previous 3. Celebrate improvements! 4. Plan next improvements if needed From 7dc80efd79ce76072445c9059ad3c563a7971903 Mon Sep 17 00:00:00 2001 From: Logan Lindquist Land Date: Sun, 21 Jun 2026 09:25:25 -0500 Subject: [PATCH 3/3] chore: gitignore private _/ dir and un-ignore docs/ ### Refactoring - Remove `docs/` from .gitignore so committed docs are tracked - Add `_/` to .gitignore as a gitignored private/scratch directory --- .gitignore | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 8bbb9c6..659f2db 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ .claude/ -docs/ + +# Private/scratch working dir (drafts, specs, outreach — not for publishing) +_/ # Dependencies node_modules/