feat: add gbrain check-update command and auto-update agent workflow (#15)
* feat: add `gbrain check-update` command for auto-update notifications Deterministic collector that checks GitHub Releases for new versions, compares semver (minor+ only, skips patches), and fetches changelog diffs. Exports `detectInstallMethod()` from upgrade.ts for reuse. Includes 15 unit tests covering version comparison, CLI wiring, and error handling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: add E2E upgrade tests against real GitHub API Exercises check-update CLI end-to-end: valid JSON output, human-readable mode, help text, graceful no-releases handling, and version comparison wiring. Skips gracefully when network is unavailable. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add SKILLPACK Section 17 — auto-update notifications Full agent playbook for the update lifecycle: check, notify, consent, upgrade, skills refresh, schema sync, report. Includes standalone self-update for skillpack-only users via version markers and raw GitHub URL fetching. Adds version markers to both SKILLPACK and RECOMMENDED_SCHEMA headers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: add auto-update step 7 to install paste, setup Phase G, migrations dir Adds step 7 to the OpenClaw install paste (default-on update checks). Setup skill gets Phase G (conditional offer for manual installs) and schema state tracking via ~/.gbrain/update-state.json. Creates skills/migrations/ directory for version-specific upgrade directives. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: update CLAUDE.md with E2E test DB lifecycle, migration conventions Adds E2E test DB lifecycle instructions (spin up, run, tear down). Documents version migration convention (skills/migrations/v[version].md) and schema state tracking (~/.gbrain/update-state.json). Updates test file counts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: broken semver comparison in extractChangelogBetween The version range check compared minor versions without guarding on major being equal, causing incorrect changelog entries to be captured (e.g., v0.5.0 would match when upgrading from v1.2.0). Extracted semverGt/semverLte helpers for correct comparisons. Added 5 tests for extractChangelogBetween covering cross-major, same-version, and malformed input cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.4.1) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -1,3 +1,5 @@
|
||||
<!-- skillpack-version: 0.4.1 -->
|
||||
<!-- source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_SKILLPACK.md -->
|
||||
# GBrain Skillpack: Reference Architecture for AI Agents
|
||||
|
||||
## 1. What This Document Is
|
||||
@@ -1091,3 +1093,127 @@ When an LLM keeps failing at a mechanical task despite repeated prompt fixes:
|
||||
This is not about the LLM being bad. It's about using the right tool for the right
|
||||
job. Code is 100% reliable at string concatenation. LLMs are 90% reliable at string
|
||||
concatenation but 10x better at understanding what an email means. Use both.
|
||||
|
||||
---
|
||||
|
||||
## 17. Auto-Update Notifications
|
||||
|
||||
GBrain ships updates frequently. The auto-update cron keeps users current by
|
||||
checking for new versions and messaging them when there's something worth upgrading to.
|
||||
|
||||
The check is automatic. The upgrade is always manual — never install without
|
||||
the user's explicit permission.
|
||||
|
||||
### The Check
|
||||
|
||||
Run `gbrain check-update --json`. If `update_available` is false, stay completely
|
||||
silent — do nothing. If true, message the user on their preferred channel.
|
||||
|
||||
### The Message
|
||||
|
||||
Summarize the `changelog_diff` into 2-3 human-friendly bullets. No raw markdown.
|
||||
Lead with the most impactful change.
|
||||
|
||||
> **GBrain v0.5.0 is available** (you're on v0.4.0)
|
||||
>
|
||||
> What's new:
|
||||
> - Semantic chunking now 3x faster with batched embedding
|
||||
> - New `gbrain files mirror` command for cloud storage migration
|
||||
> - Doctor command catches RLS misconfigurations
|
||||
>
|
||||
> Want me to upgrade? I'll update everything and refresh my playbook.
|
||||
>
|
||||
> (Reply **yes** to upgrade, **not now** to skip, **weekly** to check
|
||||
> less often, or **stop** to turn off update checks)
|
||||
|
||||
### Handling Responses
|
||||
|
||||
| User says | Action |
|
||||
|-----------|--------|
|
||||
| yes / y / sure / ok / do it / upgrade / go ahead | Run the **full upgrade flow** (see below) |
|
||||
| not now / later / skip / snooze | Acknowledge, check again next cycle |
|
||||
| weekly | Store preference in agent memory, switch cron to weekly |
|
||||
| daily | Store preference, switch cron back to daily |
|
||||
| stop / unsubscribe / no more | Store preference, disable the cron. Tell user: "Update checks disabled. Say 'resume gbrain updates' or run `gbrain check-update` anytime." |
|
||||
|
||||
Acceptable "yes": any clearly affirmative response. When in doubt, ask again.
|
||||
**Never auto-upgrade.** Always wait for explicit confirmation.
|
||||
|
||||
### The Full Upgrade Flow (after user says yes)
|
||||
|
||||
**Step 1: Update the binary/package.**
|
||||
Run `gbrain upgrade`. This updates the CLI and all shipped files (skills, docs, migrations).
|
||||
|
||||
**Step 2: Re-read all updated skills.**
|
||||
Re-read every skill file in `skills/*/SKILL.md` to pick up new patterns and workflows.
|
||||
Updated skills = better agent behavior. The user gets this for free.
|
||||
|
||||
**Step 3: Re-read the production reference docs.**
|
||||
Read `docs/GBRAIN_SKILLPACK.md` and `docs/GBRAIN_RECOMMENDED_SCHEMA.md` fresh.
|
||||
|
||||
**Step 4: Check for version-specific migration directives.**
|
||||
Look for `skills/migrations/v[version].md` files between the old and new version.
|
||||
If they exist, read and execute them in order.
|
||||
|
||||
**Step 5: Schema sync — suggest new recommendations without undoing user choices.**
|
||||
Read `~/.gbrain/update-state.json` to see what the user previously adopted, declined,
|
||||
and customized. For each NEW recommendation in the updated schema:
|
||||
- If the user never saw it before, suggest it
|
||||
- If the user previously declined it, do NOT re-suggest
|
||||
- Never modify or remove the user's custom directories
|
||||
|
||||
Update `~/.gbrain/update-state.json` with new choices and bump `schema_version_applied`.
|
||||
|
||||
**Step 6: Report what changed.**
|
||||
Tell the user what was upgraded and what actions were taken.
|
||||
|
||||
### Frequency Preferences
|
||||
|
||||
Default: daily. Store in agent memory as `gbrain_update_frequency: daily|weekly|off`.
|
||||
Also persist in `~/.gbrain/update-state.json` so it survives agent context resets.
|
||||
|
||||
### Quiet Hours
|
||||
|
||||
Standard quiet hours gate (Section 9). Update notifications are never urgent.
|
||||
Hold for morning briefing.
|
||||
|
||||
### Cron Registration
|
||||
|
||||
Name: `gbrain-update-check`
|
||||
Default schedule: `0 9 * * *` (daily 9 AM)
|
||||
Weekly schedule: `0 9 * * 1` (Monday 9 AM)
|
||||
Prompt: "Run `gbrain check-update --json`. If update_available is true, summarize
|
||||
the changelog and message me asking if I'd like to upgrade. If false, stay silent."
|
||||
|
||||
### Standalone Skillpack Users (no gbrain CLI)
|
||||
|
||||
If you loaded this SKILLPACK directly (copied the file or read from GitHub) without
|
||||
installing gbrain, you can still stay current. Both this file and
|
||||
GBRAIN_RECOMMENDED_SCHEMA.md have version markers in their first lines:
|
||||
|
||||
```
|
||||
<!-- skillpack-version: 0.4.1 -->
|
||||
<!-- source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_SKILLPACK.md -->
|
||||
```
|
||||
|
||||
**Self-update check:** Periodically fetch the first 3 lines of the source URL and
|
||||
compare the version marker against your local copy:
|
||||
|
||||
```bash
|
||||
curl -s https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_SKILLPACK.md | head -1
|
||||
# Returns: <!-- skillpack-version: X.Y.Z -->
|
||||
```
|
||||
|
||||
If the remote version is newer (minor or major bump, same rule as the CLI), fetch
|
||||
the full file and replace your local copy. Do the same for GBRAIN_RECOMMENDED_SCHEMA.md.
|
||||
|
||||
**Cron for standalone users:**
|
||||
Name: `gbrain-skillpack-update`
|
||||
Schedule: `0 9 * * 1` (weekly Monday 9 AM)
|
||||
Prompt: "Fetch the first line of https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_SKILLPACK.md
|
||||
and compare the skillpack-version against my local copy. If newer, fetch the full
|
||||
file, re-read it, and tell the user what changed. Do the same for GBRAIN_RECOMMENDED_SCHEMA.md.
|
||||
If both are current, stay silent."
|
||||
|
||||
This way standalone users get new patterns, workflows, and schema recommendations
|
||||
without installing the gbrain CLI. The agent fetches, diffs, and updates its own playbook.
|
||||
|
||||
Reference in New Issue
Block a user