mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-01 19:25:10 +02:00
feat(v1.9.0.0): gbrain-sync — cross-machine gstack memory (#1151)
* feat(gbrain-sync): queue primitives + writer shims
Adds bin/gstack-brain-enqueue (atomic append to sync queue) and
bin/gstack-jsonl-merge (git merge driver, ts-sort with SHA-256 fallback).
Wires one backgrounded enqueue call into learnings-log, timeline-log,
review-log, and developer-profile --migrate. question-log and
question-preferences stay local per Codex v2 decision.
gstack-config gains gbrain_sync_mode (off/artifacts-only/full) and
gbrain_sync_mode_prompted keys, plus GSTACK_HOME env alignment so
tests don't leak into real ~/.gstack/config.yaml.
* feat(gbrain-sync): --once drain + secret scan + push
bin/gstack-brain-sync is the core sync binary. Subcommands: --once
(drain queue, allowlist-filter, privacy-class-filter, secret-scan
staged diff, commit with template, push with fetch+merge retry),
--status, --skip-file <path>, --drop-queue --yes, --discover-new
(cursor-based detection of artifact writes that skip the shim).
Secret regex families: AWS keys, GitHub tokens (ghp_/gho_/ghu_/ghs_/
ghr_/github_pat_), OpenAI sk-, PEM blocks, JWTs, bearer-token-in-JSON.
On hit: unstage, preserve queue, print remediation hint (--skip-file
or edit), exit clean. No daemon — invoked by preamble at skill
boundaries.
* feat(gbrain-sync): init, restore, uninstall, consumer registry
bin/gstack-brain-init: idempotent first-run. git init ~/.gstack/,
.gitignore=*, canonical .brain-allowlist + .brain-privacy-map.json,
pre-commit secret-scan hook (defense-in-depth), merge driver registration
via git config, gh repo create --private OR arbitrary --remote <url>,
initial push, ~/.gstack-brain-remote.txt for new-machine discovery,
GBrain consumer registration via HTTP POST.
bin/gstack-brain-restore: safe new-machine bootstrap. Refuses clobber
of existing allowlisted files, clones to staging, rsync-copies tracked
files, re-registers merge drivers (required — not cloned from remote),
rehydrates consumers.json, prompts for per-consumer tokens.
bin/gstack-brain-uninstall: clean off-ramp. Removes .git + .brain-*
files + consumers.json + config keys. Preserves user data (learnings,
plans, retros, profile). Optional --delete-remote for GitHub repos.
bin/gstack-brain-consumer + bin/gstack-brain-reader (symlink alias):
registry management. Internal 'consumer' term; user-facing 'reader'
per DX review decision.
* feat(gbrain-sync): preamble block — privacy gate + boundary sync
scripts/resolvers/preamble/generate-brain-sync-block.ts emits bash that
runs at every skill invocation:
- Detects ~/.gstack-brain-remote.txt on machines without local .git
and surfaces a restore-available hint (does NOT auto-run restore).
- Runs gstack-brain-sync --once at skill start to drain any pending
writes (and at skill end via prose instruction).
- Once-per-day auto-pull (cached via .brain-last-pull) for append-only
JSONL files.
- Emits BRAIN_SYNC: status line every skill run.
Also emits prose for the host LLM to fire the one-time privacy
stop-gate (full / artifacts-only / off) when gbrain is detected and
gbrain_sync_mode_prompted is false. Wired into preamble.ts composition.
* test(gbrain-sync): 27-test consolidated suite
test/brain-sync.test.ts covers:
- Config: validation, defaults, GSTACK_HOME env isolation
- Enqueue: no-op gates, skip list, concurrent atomicity, JSON escape
- JSONL merge driver: 3-way + ts-sort + SHA-256 fallback
- Init + sync: canonical file creation, merge driver registration,
push-reject + fetch+merge retry path
- Init refuses different remote (idempotency)
- Cross-machine restore round-trip (machine A write → machine B sees)
- Secret scan across all 6 regex families (AWS, GH, OpenAI, PEM, JWT,
bearer-JSON). --skip-file unblock remediation
- Uninstall removes sync config, preserves user data
- --discover-new idempotence via mtime+size cursor
Behaviors verified via integration smokes during implementation. Known
follow-up: bun-test 5s default timeout needs 30s wrapper for
spawnSync-heavy tests.
* docs(gbrain-sync): user guide + error lookup + README section
docs/gbrain-sync.md: setup walkthrough, privacy modes, cross-machine
workflow, secret protection, two-machine conflict handling, uninstall,
troubleshooting reference.
docs/gbrain-sync-errors.md: problem/cause/fix index for every
user-visible error. Patterned on Rust's error docs + Stripe's API
error reference.
README.md: 'Cross-machine memory with GBrain sync' section near the
top (discovery moment), plus docs-table entry.
* chore: bump version and changelog (v1.7.0.0)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* chore: regenerate SKILL.md files for gbrain-sync preamble block
Re-runs bun run gen:skill-docs after adding generateBrainSyncBlock
to scripts/resolvers/preamble.ts in a2aa8a07. CI check-freshness
caught the drift. All 36 SKILL.md files regenerated with the new
skill-start bash block + privacy-gate prose + skill-end sync
instructions baked in.
* fix(test): session-awareness reads AskUserQuestion Format from a Tier 2+ SKILL.md
The test was reading ROOT/SKILL.md (browse skill, Tier 1) which never
contained '## AskUserQuestion Format' — that section is only emitted
for Tier 2+ skills by scripts/resolvers/preamble.ts. As a result the
agent was prompted with an empty format guide and only emitted
'RECOMMENDATION' intermittently, making the test flaky.
Pre-existing on main (same ROOT/SKILL.md shape there) — surfaced now
because the agent run didn't hit the RECOMMENDATION/recommend/option a
fallback strings in this particular attempt.
Fix: read from office-hours/SKILL.md (Tier 3, always has the section)
with a fallback that scans for the first top-level skill dir whose
SKILL.md contains the header. Future template moves won't break this
test again.
* chore: bump to v1.9.0.0 for gbrain-sync landing
Changes just the VERSION + package.json + CHANGELOG header (1.7.0.0 → 1.9.0.0
and date 2026-04-22 → 2026-04-23). No code changes. User call: land gbrain-sync
as a bigger-signal release above main's 1.6.4.0, skipping 1.8.0.0.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
Executable
+145
@@ -0,0 +1,145 @@
|
||||
#!/usr/bin/env bash
|
||||
# gstack-brain-uninstall — clean off-ramp for gstack-brain sync.
|
||||
#
|
||||
# Usage:
|
||||
# gstack-brain-uninstall [--yes] [--delete-remote]
|
||||
#
|
||||
# Removes the git layer from ~/.gstack/ and clears sync config. Your local
|
||||
# gstack memory (learnings, timelines, etc.) is NOT touched — this is an
|
||||
# uninstall-sync command, not a delete-data command.
|
||||
#
|
||||
# Flags:
|
||||
# --yes Skip the confirmation prompt.
|
||||
# --delete-remote Also delete the GitHub repo via `gh repo delete`
|
||||
# (interactive unless --yes is also passed).
|
||||
#
|
||||
# What it removes (in ~/.gstack/):
|
||||
# .git/ — the sync repo's git data
|
||||
# .gitignore — canonical ignore-all marker
|
||||
# .gitattributes — merge driver declarations
|
||||
# .brain-allowlist — sync path list
|
||||
# .brain-privacy-map.json — sync privacy classifier
|
||||
# .brain-queue.jsonl — pending queue
|
||||
# .brain-discover-cursor — discover-new cursor
|
||||
# .brain-last-push — timestamp marker
|
||||
# .brain-skip.txt — user-maintained skip list
|
||||
# .brain-sync.lock.d/ — lock dir (if present)
|
||||
# .brain-sync-status.json — health status
|
||||
# consumers.json — consumer/reader registry
|
||||
#
|
||||
# What it clears (via gstack-config):
|
||||
# gbrain_sync_mode → off
|
||||
# gbrain_sync_mode_prompted → false (so user re-prompts on re-init)
|
||||
#
|
||||
# What it does NOT touch:
|
||||
# Project data (projects/*, retros/*, developer-profile.json, etc.)
|
||||
# Consumer tokens in gstack-config (<name>_token keys)
|
||||
# ~/.gstack-brain-remote.txt in your home directory
|
||||
# The actual remote git repo (unless --delete-remote)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
CONFIG_BIN="$SCRIPT_DIR/gstack-config"
|
||||
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
|
||||
|
||||
ASSUME_YES=0
|
||||
DELETE_REMOTE=0
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--yes|-y) ASSUME_YES=1; shift ;;
|
||||
--delete-remote) DELETE_REMOTE=1; shift ;;
|
||||
--help|-h) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
|
||||
*) echo "Unknown flag: $1" >&2; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [ ! -d "$GSTACK_HOME/.git" ]; then
|
||||
echo "gstack-brain-uninstall: nothing to do (~/.gstack/.git doesn't exist)."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
REMOTE_URL=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
|
||||
|
||||
# ---- confirmation ----
|
||||
if [ "$ASSUME_YES" != "1" ]; then
|
||||
cat <<EOF
|
||||
This will remove gstack-brain sync from this machine:
|
||||
- Remove ~/.gstack/.git and sync config files
|
||||
- Clear gbrain_sync_mode in gstack-config
|
||||
- Remote: $REMOTE_URL will be $([ "$DELETE_REMOTE" = "1" ] && echo "DELETED" || echo "kept")
|
||||
|
||||
Local memory (learnings, plans, etc.) is NOT touched.
|
||||
|
||||
EOF
|
||||
printf "Proceed? [y/N] "
|
||||
read -r reply
|
||||
case "$reply" in
|
||||
y|Y|yes|Yes) ;;
|
||||
*) echo "Aborted."; exit 0 ;;
|
||||
esac
|
||||
fi
|
||||
|
||||
# ---- delete remote if requested ----
|
||||
if [ "$DELETE_REMOTE" = "1" ] && [ -n "$REMOTE_URL" ]; then
|
||||
case "$REMOTE_URL" in
|
||||
*github.com*|*@github*)
|
||||
if command -v gh >/dev/null 2>&1; then
|
||||
# Extract owner/repo from URL.
|
||||
REPO_SLUG=$(echo "$REMOTE_URL" | sed -E 's#.*[:/]([^/:]+/[^/]+)(\.git)?$#\1#' | sed 's/\.git$//')
|
||||
if [ -n "$REPO_SLUG" ]; then
|
||||
echo "Deleting GitHub repo: $REPO_SLUG"
|
||||
if [ "$ASSUME_YES" = "1" ]; then
|
||||
gh repo delete "$REPO_SLUG" --yes 2>/dev/null || echo "gh repo delete failed; continuing local uninstall"
|
||||
else
|
||||
gh repo delete "$REPO_SLUG" 2>/dev/null || echo "gh repo delete failed; continuing local uninstall"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
echo "--delete-remote requires the gh CLI. Skipping remote deletion."
|
||||
fi
|
||||
;;
|
||||
*)
|
||||
echo "--delete-remote only supports github.com remotes. Delete manually if needed: $REMOTE_URL"
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
# ---- remove sync files ----
|
||||
echo "Removing git layer and sync config files..."
|
||||
rm -rf "$GSTACK_HOME/.git" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.gitignore" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.gitattributes" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-allowlist" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-privacy-map.json" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-queue.jsonl" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-discover-cursor" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-last-push" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-last-pull" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-skip.txt" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/.brain-sync-status.json" 2>/dev/null || true
|
||||
rm -rf "$GSTACK_HOME/.brain-sync.lock.d" 2>/dev/null || true
|
||||
rm -f "$GSTACK_HOME/consumers.json" 2>/dev/null || true
|
||||
|
||||
# ---- clear config keys ----
|
||||
"$CONFIG_BIN" set gbrain_sync_mode off >/dev/null 2>&1 || true
|
||||
"$CONFIG_BIN" set gbrain_sync_mode_prompted false >/dev/null 2>&1 || true
|
||||
|
||||
# ---- leave remote-helper file alone unless user asked to delete remote ----
|
||||
if [ "$DELETE_REMOTE" = "1" ]; then
|
||||
rm -f "$REMOTE_FILE" 2>/dev/null || true
|
||||
else
|
||||
if [ -f "$REMOTE_FILE" ]; then
|
||||
echo "(keeping $REMOTE_FILE — remove manually if you want to forget the URL)"
|
||||
fi
|
||||
fi
|
||||
|
||||
cat <<EOF
|
||||
|
||||
gstack-brain uninstall complete.
|
||||
Sync is off. ~/.gstack/ is a plain directory again.
|
||||
Your project data, learnings, and profile are untouched.
|
||||
|
||||
To re-enable sync later: gstack-brain-init
|
||||
EOF
|
||||
Reference in New Issue
Block a user