youmd 0.6.27 → 0.7.1

package/scripts/skillstack-sync/README.md

@@ -0,0 +1,166 @@
+# skillstack-sync
+
+Cross-machine sync toolkit for Houston Golden's agent skill/stack setup.
+
+## What this syncs
+
+### Sync plane: Skills & Stacks (this toolkit)
+
+| What | How | Notes |
+|---|---|---|
+| `~/.agent-shared` | git push/pull to `houstongolden/agent-shared` | Canonical shared agent layer: AGENTS.md, learnings, preferences, STACK-MAP |
+| `~/.claude/scistack` | git push/pull to `Hubify-Projects/scistack` | Science skills: astrostack, hubstack, extensions |
+| 4 loose skills (see below) | rsync into agent-shared repo, then back out | Ride along in agent-shared without their own repo |
+
+**Loose skills synced via agent-shared/claude-skills/:**
+- `agent-runtime-guard`
+- `agent-stack-sync`
+- `continue`
+- `skill-governor`
+
+### What does NOT sync here
+
+| What | Why |
+|---|---|
+| `~/.claude/skills/gstack/` | Tracks upstream `garrytan/gstack` — updated via `/gstack-upgrade`, read-only to us |
+| Project files / code | Synced via their own project repos (youmd, bamfaiapp, etc.) |
+| Secrets / env vars | Use the env-vault (`cli/scripts/env-vault/`) |
+
+### Complementary sync planes
+
+- **Identity plane:** `youmd sync` (Convex ↔ local profile, memories, preferences). Automated via `com.youmd.identity-sync` daemon.
+- **Env-vault plane:** `cli/scripts/env-vault/restore.sh` for secrets (manual, invoked on new machine); also available as `youmd env restore <vault>`.
+
+---
+
+## Files
+
+```
+cli/scripts/skillstack-sync/
+├── sync.sh                         Core syncer (bash 3.2 compatible)
+├── install-daemons.sh              Installs both LaunchAgents
+├── bootstrap-new-mac.sh            New machine setup script
+├── com.youmd.skillstack-sync.plist LaunchAgent: runs `youmd stack sync` every 5 min
+├── com.youmd.identity-sync.plist   LaunchAgent: runs `youmd sync` every 5 min
+└── README.md                       This file
+```
+
+---
+
+## Sync logic (sync.sh)
+
+```
+1. Mirror loose skills:  ~/.claude/skills/<name>/ → ~/.agent-shared/claude-skills/<name>/
+2. Sync ~/.agent-shared:
+     a. git add -A + commit "auto-sync: <host> <timestamp>" if dirty
+     b. git pull --no-rebase --no-edit (merge)
+        → on conflict: abort merge, log LOUD warning, skip push, continue
+     c. git push
+3. Sync ~/.claude/scistack: same a/b/c sequence
+4. Reverse-mirror loose skills: ~/.agent-shared/claude-skills/<name>/ → ~/.claude/skills/<name>/
+     → backs up existing local copy to <name>.bak.<timestamp> before overwriting
+     → skips if no changes detected
+```
+
+All actions logged to `~/.youmd/logs/skillstack-sync.log`.
+
+### Flags
+
+```bash
+youmd stack sync              # live sync (all repos + loose skills)
+youmd stack sync --dry-run    # log what WOULD happen, write nothing
+
+# or run the script directly:
+./sync.sh
+./sync.sh --dry-run
+```
+
+### Env overrides
+
+```bash
+SKILLSTACK_REPOS="/path/to/repo1 /path/to/repo2"  # override repo list
+GIT_USER_NAME="Houston Golden"                      # commit author (default)
+GIT_USER_EMAIL="houston@bamf.ai"                    # commit email (default)
+```
+
+---
+
+## Daemon setup (existing machine)
+
+The preferred way is via the CLI:
+
+```bash
+youmd stack daemon install    # installs both LaunchAgents
+youmd stack daemon status     # check loaded/not-loaded
+youmd stack daemon uninstall  # remove plists from ~/Library/LaunchAgents/
+```
+
+Or run the raw script directly:
+
+```bash
+bash cli/scripts/skillstack-sync/install-daemons.sh
+```
+
+Installs two LaunchAgents that fire every 300 seconds (5 minutes):
+- `com.youmd.skillstack-sync` → runs `youmd stack sync`
+- `com.youmd.identity-sync` → runs `youmd sync`
+
+Check status:
+```bash
+youmd stack daemon status
+# or directly:
+launchctl list com.youmd.skillstack-sync
+launchctl list com.youmd.identity-sync
+```
+
+Check logs:
+```bash
+tail -f ~/.youmd/logs/skillstack-sync.log
+tail -f ~/.youmd/logs/skillstack-sync.out.log
+tail -f ~/.youmd/logs/identity-sync.out.log
+```
+
+### Uninstall daemons
+
+```bash
+youmd stack daemon uninstall
+```
+
+Or manually:
+```bash
+launchctl unload ~/Library/LaunchAgents/com.youmd.skillstack-sync.plist
+launchctl unload ~/Library/LaunchAgents/com.youmd.identity-sync.plist
+rm ~/Library/LaunchAgents/com.youmd.skillstack-sync.plist
+rm ~/Library/LaunchAgents/com.youmd.identity-sync.plist
+```
+
+---
+
+## New Mac setup
+
+```bash
+# 1. Install youmd CLI
+curl -fsSL https://you.md/install.sh | bash
+
+# 2. Clone this repo (youmd)
+git clone https://github.com/houstongolden/youmd ~/Desktop/CODE_2025/youmd
+
+# 3. Run bootstrap (clones agent-shared + scistack)
+bash ~/Desktop/CODE_2025/youmd/cli/scripts/skillstack-sync/bootstrap-new-mac.sh
+
+# 4. Restore secrets from env-vault (manual step — see env-vault/README)
+
+# 5. Activate daemons
+youmd stack daemon install
+```
+
+The bootstrap script is idempotent (safe to re-run).
+
+---
+
+## Compatibility
+
+Scripts target macOS with:
+- bash 3.2.57 (default macOS shell)
+- BSD coreutils (no GNU `mapfile`, no `mktemp --suffix`, BSD `date`/`find`/`rsync`)
+- No external tools installed beyond: `git`, `rsync`, `bash` (all stock on macOS)

package/scripts/skillstack-sync/bootstrap-new-mac.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# bootstrap-new-mac.sh — set up a new Mac with Houston's agent skill/stack layer
+#
+# Safe to re-run (idempotent). Prints all steps before executing them.
+# Does NOT run launchctl, does NOT push git, does NOT install anything
+# beyond youmd CLI and git clones.
+#
+# After this script: run install-daemons.sh to activate the sync daemons.
+#
+# Usage: bash bootstrap-new-mac.sh
+
+set -euo pipefail
+
+AGENT_SHARED="${HOME}/.agent-shared"
+SCISTACK="${HOME}/.claude/scistack"
+CLAUDE_SKILLS="${HOME}/.claude/skills"
+
+LOOSE_SKILLS="agent-runtime-guard agent-stack-sync continue skill-governor"
+
+AGENT_SHARED_REPO="https://github.com/houstongolden/agent-shared.git"
+SCISTACK_REPO="https://github.com/Hubify-Projects/scistack.git"
+
+step() {
+  echo ""
+  echo "===> $*"
+}
+
+info() {
+  echo "     $*"
+}
+
+warn() {
+  echo "     WARN: $*"
+}
+
+# ---------------------------------------------------------------------------
+step "1. Install youmd CLI"
+# ---------------------------------------------------------------------------
+if command -v youmd >/dev/null 2>&1; then
+  info "youmd already installed: $(youmd --version 2>/dev/null || echo '(version unknown)')"
+else
+  info "Installing youmd via official install script..."
+  curl -fsSL https://you.md/install.sh | bash
+  info "youmd installed."
+fi
+
+# ---------------------------------------------------------------------------
+step "2. Clone agent-shared repo → ${AGENT_SHARED}"
+# ---------------------------------------------------------------------------
+if [ -d "${AGENT_SHARED}/.git" ]; then
+  info "Already present: ${AGENT_SHARED} — skipping clone."
+else
+  info "Cloning ${AGENT_SHARED_REPO} → ${AGENT_SHARED}"
+  mkdir -p "$(dirname "${AGENT_SHARED}")"
+  # Use gh if available for credential handling; fall back to git
+  if command -v gh >/dev/null 2>&1; then
+    gh repo clone houstongolden/agent-shared "${AGENT_SHARED}"
+  else
+    git clone "${AGENT_SHARED_REPO}" "${AGENT_SHARED}"
+  fi
+  info "Cloned agent-shared."
+fi
+
+# ---------------------------------------------------------------------------
+step "3. Clone scistack repo → ${SCISTACK}"
+# ---------------------------------------------------------------------------
+if [ -d "${SCISTACK}/.git" ]; then
+  info "Already present: ${SCISTACK} — skipping clone."
+else
+  info "Cloning ${SCISTACK_REPO} → ${SCISTACK}"
+  mkdir -p "$(dirname "${SCISTACK}")"
+  if command -v gh >/dev/null 2>&1; then
+    gh repo clone Hubify-Projects/scistack "${SCISTACK}"
+  else
+    git clone "${SCISTACK_REPO}" "${SCISTACK}"
+  fi
+  info "Cloned scistack."
+fi
+
+# ---------------------------------------------------------------------------
+step "4. Restore loose skills from agent-shared/claude-skills/ → ~/.claude/skills/"
+# ---------------------------------------------------------------------------
+mkdir -p "${CLAUDE_SKILLS}"
+
+for skill in ${LOOSE_SKILLS}; do
+  src="${AGENT_SHARED}/claude-skills/${skill}"
+  dst="${CLAUDE_SKILLS}/${skill}"
+
+  if [ ! -d "${src}" ]; then
+    warn "Loose skill '${skill}' not found in agent-shared yet — will be populated on first sync."
+    continue
+  fi
+
+  if [ -d "${dst}" ]; then
+    info "Skill '${skill}' already exists at ${dst} — skipping (run sync.sh to update)."
+  else
+    info "Restoring skill '${skill}' → ${dst}"
+    rsync -a "${src}/" "${dst}/"
+    info "Restored ${skill}."
+  fi
+done
+
+# ---------------------------------------------------------------------------
+step "5. Reminder: restore secrets"
+# ---------------------------------------------------------------------------
+echo ""
+echo "  !! IMPORTANT: Secrets are NOT in git. Restore them separately:"
+echo ""
+echo "     If you use the env-vault (~/Desktop/CODE_2025/youmd/cli/scripts/env-vault/):"
+echo "       youmd env restore <vault-file>   # CLI wrapper (preferred)"
+echo "       bash ~/Desktop/CODE_2025/youmd/cli/scripts/env-vault/restore.sh <vault-file>"
+echo ""
+echo "     Secrets to restore (set in your shell profile or .env files):"
+echo "       OPENROUTER_API_KEY"
+echo "       CONVEX_DEPLOY_KEY"
+echo "       YOUMD_API_KEY"
+echo "       GH_TOKEN (or: gh auth login)"
+echo "       ANTHROPIC_API_KEY"
+echo ""
+
+# ---------------------------------------------------------------------------
+step "6. Next steps"
+# ---------------------------------------------------------------------------
+echo ""
+echo "  Bootstrap complete. To activate the auto-sync daemons, run:"
+echo ""
+echo "    youmd stack daemon install        # preferred (CLI-native)"
+echo ""
+echo "  Or run the raw script directly:"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "    bash ${SCRIPT_DIR}/install-daemons.sh"
+echo ""
+echo "  To do a manual sync now:"
+echo "    youmd stack sync                  # preferred (CLI-native)"
+echo ""
+echo "  To do a dry-run first (recommended):"
+echo "    youmd stack sync --dry-run"
+echo ""
+echo "================================================================"
+echo "Bootstrap done. Welcome to the new machine."
+echo "================================================================"

package/scripts/skillstack-sync/com.youmd.identity-sync.plist

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.youmd.identity-sync</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/zsh</string>
+        <string>-lc</string>
+        <string>youmd sync</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>300</integer>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <false/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.youmd/logs/identity-sync.out.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.youmd/logs/identity-sync.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>__HOME__</string>
+    </dict>
+</dict>
+</plist>

package/scripts/skillstack-sync/com.youmd.skillstack-sync.plist

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.youmd.skillstack-sync</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/zsh</string>
+        <string>-lc</string>
+        <string>youmd stack sync</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>300</integer>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <false/>
+
+    <key>StandardOutPath</key>
+    <string>__HOME__/.youmd/logs/skillstack-sync.out.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>__HOME__/.youmd/logs/skillstack-sync.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>__HOME__</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+</dict>
+</plist>

package/scripts/skillstack-sync/install-daemons.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# install-daemons.sh — install skillstack-sync and identity-sync LaunchAgents
+#
+# Idempotent: safe to re-run. Unloads before reloading.
+# Does NOT need sudo — LaunchAgents run as the current user.
+#
+# Usage: ./install-daemons.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LAUNCH_AGENTS_DIR="${HOME}/Library/LaunchAgents"
+LOG_DIR="${HOME}/.youmd/logs"
+
+PLISTS="com.youmd.skillstack-sync com.youmd.identity-sync"
+
+echo "==> Creating log directory: ${LOG_DIR}"
+mkdir -p "${LOG_DIR}"
+
+echo "==> Creating LaunchAgents directory: ${LAUNCH_AGENTS_DIR}"
+mkdir -p "${LAUNCH_AGENTS_DIR}"
+
+for label in ${PLISTS}; do
+  src="${SCRIPT_DIR}/${label}.plist"
+  dst="${LAUNCH_AGENTS_DIR}/${label}.plist"
+
+  if [ ! -f "${src}" ]; then
+    echo "ERROR: Source plist not found: ${src}" >&2
+    exit 1
+  fi
+
+  echo ""
+  echo "--- Installing ${label} ---"
+
+  # Substitute __HOME__ placeholder with actual home dir
+  # BSD sed: use a temp file, no -i '' in-place on stdin
+  local_tmp="$(mktemp -t youmd_plist)"
+  sed "s|__HOME__|${HOME}|g" "${src}" > "${local_tmp}"
+
+  # Unload existing daemon if loaded (ignore errors — it may not be loaded)
+  if launchctl list "${label}" >/dev/null 2>&1; then
+    echo "  Unloading existing ${label}..."
+    launchctl unload "${dst}" 2>/dev/null || true
+  fi
+
+  echo "  Copying ${label}.plist → ${LAUNCH_AGENTS_DIR}/"
+  cp "${local_tmp}" "${dst}"
+  rm -f "${local_tmp}"
+
+  echo "  Loading ${label}..."
+  launchctl load -w "${dst}"
+
+  echo "  Loaded: ${label}"
+done
+
+echo ""
+echo "================================================================"
+echo "Both daemons installed and running."
+echo ""
+echo "Log files:"
+echo "  ${LOG_DIR}/skillstack-sync.log      (combined sync log)"
+echo "  ${LOG_DIR}/skillstack-sync.out.log  (daemon stdout)"
+echo "  ${LOG_DIR}/skillstack-sync.err.log  (daemon stderr)"
+echo "  ${LOG_DIR}/identity-sync.out.log    (youmd sync stdout)"
+echo "  ${LOG_DIR}/identity-sync.err.log    (youmd sync stderr)"
+echo ""
+echo "Check daemon status:"
+echo "  launchctl list com.youmd.skillstack-sync"
+echo "  launchctl list com.youmd.identity-sync"
+echo ""
+echo "To uninstall:"
+for label in ${PLISTS}; do
+  echo "  launchctl unload ${LAUNCH_AGENTS_DIR}/${label}.plist && rm ${LAUNCH_AGENTS_DIR}/${label}.plist"
+done
+echo "================================================================"