@quickcall/all-configs 0.0.0-stage → 1.0.0

package/runtime/modules/hf/install.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$ROOT_DIR/lib/common.sh"
+
+usage() {
+  cat << USAGE
+Usage: ${0##*/} [options]
+
+Options:
+  -t, --token <token>  Hugging Face access token (optional)
+  -h, --help           Show this help
+
+Environment variables:
+  HF_TOKEN             Hugging Face access token
+
+Examples:
+  ${0##*/}
+  ${0##*/} -t hf_...
+  HF_TOKEN=hf_... ${0##*/}
+USAGE
+  exit 0
+}
+
+TOKEN="${HF_TOKEN:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--token) TOKEN="$2"; shift 2 ;;
+    -h|--help) usage ;;
+    *) fail "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+step "Ensuring uv"
+if command -v uv &> /dev/null; then
+    ok "uv ${D}$(uv --version)${R}"
+else
+    warn "uv not found — installing"
+    curl -LsSf https://astral.sh/uv/install.sh | bash
+    export PATH="$HOME/.local/bin:$PATH"
+    ok "uv installed ${D}$(uv --version)${R}"
+fi
+
+step "Installing Hugging Face CLI"
+
+if command -v hf &> /dev/null; then
+  ok "hf ${D}$(hf --version)${R}"
+else
+  if [[ "$PLATFORM" == "linux" ]] && command -v apt-get &>/dev/null; then
+    step "Ensuring Python venv support"
+    sudo apt-get update -qq
+    sudo apt-get install -y -qq python3-venv python3.12-venv || sudo apt-get install -y -qq python3-venv
+    ok "python venv support present"
+  fi
+
+  warn "hf not found - installing via hf.co/install.sh"
+  curl -LsSf https://hf.co/cli/install.sh | bash
+
+  # Add to PATH if installed in a user-local directory
+  if [[ -d "$HOME/.local/bin" ]] && [[ -f "$HOME/.local/bin/hf" ]]; then
+    for rc in "$HOME/.zshrc" "$HOME/.bashrc"; do
+      [[ -f "$rc" ]] || continue
+      if ! grep -q "\.local/bin" "$rc" 2>/dev/null; then
+        printf '\n# hf cli\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$rc"
+        ok "added ~/.local/bin to PATH in $(basename "$rc")"
+      else
+        ok "~/.local/bin already in PATH in $(basename "$rc")"
+      fi
+    done
+  fi
+fi
+
+# Ensure hf is on PATH for the rest of this script
+export PATH="$HOME/.local/bin:$PATH"
+ok "hf ${D}$(hf --version)${R}"
+
+step "Configuring git credential helper"
+if [[ "$(git config --global credential.helper)" != "store" ]]; then
+  git config --global credential.helper store
+  ok "git credential.helper set to store"
+else
+  ok "git credential.helper already set to store"
+fi
+
+if [[ -n "$TOKEN" ]]; then
+  step "Authenticating with Hugging Face"
+  hf auth login --token "$TOKEN" --add-to-git-credential
+  ok "HF authentication saved"
+else
+  warn "No HF_TOKEN provided - run hf auth login manually"
+fi
+
+echo ""
+echo -e "  ${GRN}Done!${R} Run ${CYN}hf whoami${R} to verify"
+echo ""

package/runtime/modules/hf/module.toml

@@ -0,0 +1,7 @@
+name = "hf"
+description = "Hugging Face CLI (hf) via hf.co/install.sh"
+platforms = ["mac", "linux"]
+kind = "cli"
+
+[detect]
+commands = ["hf"]

package/runtime/modules/karabiner/README.md

@@ -0,0 +1,146 @@
+# Karabiner Config
+
+Local Karabiner-Elements config for this repo. Karabiner-Elements is macOS only.
+
+## Install / Sync
+
+```bash
+./karabiner/install.sh
+```
+
+This syncs `karabiner/` to `~/.config/karabiner/karabiner_scripts/` and installs `karabiner.json` to `~/.config/karabiner/karabiner.json` (the live config Karabiner reads), then relaunches Karabiner-Elements.
+
+If you edit configs by hand instead, keep these in sync:
+
+1. The modular file in this directory (e.g. `app_launchers.json`)
+2. `karabiner.json` in this directory (merged copy)
+3. The live config at `~/.config/karabiner/karabiner.json`
+
+Karabiner watches the live config and reloads automatically (see `~/.local/share/karabiner/log/console_user_server.log` for `core_configuration is updated`).
+
+## Keymap
+
+### Caps Lock
+
+| From | To | Description |
+|------|-----|-------------|
+| `Caps Lock` | `Ctrl+Shift+Option+Cmd` (super) | Caps Lock becomes a hyper key |
+
+### Application shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Caps + B` | Open/switch to **Brave Browser** |
+| `Caps + C` | Open/switch to **Claude** |
+| `Caps + D` | Open/switch to **Visual Studio Code** |
+| `Caps + F` | Open/switch to **Finder** |
+| `Caps + G` | Open/switch to **ChatGPT** |
+| `Caps + L` | Clear terminal (sends `Ctrl + L`) |
+| `Caps + M` | Open/switch to **WhatsApp** |
+| `Caps + N` | Open/switch to **Granola** |
+| `Caps + O` | Open/switch to **Obsidian** |
+| `Caps + S` | Open/switch to **Slack** |
+| `Caps + T` | Open/switch to **Ghostty** |
+| `Caps + W` | Open/switch to **WhatsApp Web** |
+
+### Modifier behavior
+
+| From | To | Description |
+|------|-----|-------------|
+| `Fn` (built-in keyboard) | `Left Control` | Fn key acts as Left Control |
+| `Left Control` (tapped) | `Escape` | Control becomes Escape when tapped alone |
+| `Left Control` (held) | `Control` | Normal Control when used with other keys |
+| `Right Control` (tapped) | `Escape` | Same as above, right side |
+| `Right Control` (held) | `Control` | Same as above, right side |
+| `Right Shift` (tapped) | Right Mouse Click | Quick right-click |
+| `Right Shift` (held) | `Shift` | Normal Shift when used with other keys |
+
+### Option/Command swap (Keychron K3 Pro only)
+
+Device-scoped `simple_modifications` on the Keychron (`vendor_id: 13364`), applied in firmware order (emitted codes are pre-swap):
+
+| From | To |
+|------|-----|
+| `Left Command` | `Left Option` |
+| `Left Option` | `Left Command` |
+| `Right Command` | `Right Option` |
+| `Right Option` | `Right Command` |
+
+Do **not** make this a global swap — it would break the MacBook built-in keyboard. See [troubleshooting.md](./troubleshooting.md) for why.
+
+### Vim-style navigation (HJKL)
+
+#### Basic movement
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl + H` | Left Arrow |
+| `Ctrl + J` | Down Arrow |
+| `Ctrl + K` | Up Arrow |
+| `Ctrl + L` | Right Arrow |
+
+#### Word-level movement
+
+| Shortcut | Action |
+|----------|--------|
+| `Option + H/J/K/L` | Move by word left/down/up/right |
+
+#### Line/document movement
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl + Cmd + H` | Move to line start |
+| `Ctrl + Cmd + J` | Move to document end |
+| `Ctrl + Cmd + K` | Move to document start |
+| `Ctrl + Cmd + L` | Move to line end |
+
+#### Selection
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl + Shift + H/J/K/L` | Select left/down/up/right |
+| `Option + Shift + H/J/K/L` | Select word left/down/up/right |
+| `Ctrl + Cmd + Shift + H` | Select to line start |
+| `Ctrl + Cmd + Shift + J` | Select to document end |
+| `Ctrl + Cmd + Shift + K` | Select to document start |
+| `Ctrl + Cmd + Shift + L` | Select to line end |
+
+### Delete / mouse
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl + D` | Forward delete (single character) |
+| `Escape` | Left Mouse Click |
+
+## Key symbols
+
+| Symbol | Key |
+|--------|-----|
+| `⌘` | Command |
+| `⌃` | Control |
+| `⌥` | Option/Alt |
+| `⇧` | Shift |
+| `⇪` | Caps Lock |
+| `⎋` | Escape |
+| `⌦` | Delete (Forward) |
+| `⌫` | Delete (Backward) |
+| `←` `→` `↑` `↓` | Arrow Keys |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `karabiner.json` | Merged config, installed to live config by `install.sh` |
+| `app_launchers.json` | Modular: app shortcuts (Caps+letter) |
+| `vim_arrow_keys.json` | Modular: HJKL navigation |
+| `rename_caps_lock_to_super.json` | Modular: Caps Lock -> super |
+| `remap_caps_lock_shift_super.json` | Modular: Caps+Shift escape variant |
+| `remap_escape_to_control.json` | Modular: Esc -> Ctrl, tap for Escape |
+| `fn_to_control.json` | Modular: Fn -> Left Control |
+| `custom_delete_mapping.json` | Modular: Ctrl+D forward delete |
+| `right_shift_mouse_click.json` | Modular: Right Shift tap -> right click |
+| `swap_esc_delete.json` | Modular: swap Esc/Delete |
+| `install.sh` | Syncs repo -> live config, relaunches Karabiner |
+| `keychron-modifier-swap.sh` | Helper for Keychron device entries |
+| `troubleshooting.md` | Keychron modifier/Caps incident log + debug playbook |
+| `agents.md` | Context for AI agents editing this config |

package/runtime/modules/karabiner/agents.md

@@ -0,0 +1,39 @@
+# Agent Context: Karabiner Config
+
+## Layout
+
+This directory (`./karabiner/` in the `all-configs` dotfiles repo) is the source of truth. It is synced to the live location by `install.sh`:
+
+```
+<repo>/karabiner/                     # source of truth (this directory, git)
+└── installed/synced to:
+    ~/.config/karabiner/
+    ├── karabiner.json                # LIVE config — Karabiner-Elements reads this
+    └── karabiner_scripts/            # rsync copy of this directory (install.sh)
+```
+
+## Key rules
+
+1. **Caps Lock = super** (`left_control + left_shift + left_option + left_command`). All `Caps + <key>` shortcuts use that modifier combo.
+
+2. **Keep all copies in sync** when changing shortcuts:
+   - The modular file here (e.g. `app_launchers.json`)
+   - The merged `karabiner.json` here
+   - `~/.config/karabiner/karabiner.json` (live)
+   - `~/.config/karabiner/karabiner_scripts/` (rsync copy — or rerun `install.sh` to regenerate)
+
+   Karabiner watches the live config and reloads automatically; check `~/.local/share/karabiner/log/console_user_server.log` for `core_configuration is updated`.
+
+3. **App names vs bundle IDs** — `open -a 'App Name'` sometimes fails (e.g. WhatsApp). Use `open -b 'bundle.id'` as fallback. Get bundle ID via:
+   ```bash
+   mdls -name kMDItemCFBundleIdentifier /Applications/AppName.app
+   ```
+
+4. **Validate JSON** after editing:
+   ```bash
+   jq empty <file>
+   ```
+
+5. **Git** — commit and push from the `all-configs` repo root (`git@github.com:quickcall-dev/all-configs.git`).
+
+6. **Never add global Command/Option swaps** — they break the MacBook built-in keyboard. Keychron corrections are device-scoped only. See `troubleshooting.md` before touching modifier rules.

package/runtime/modules/karabiner/app_launchers.json

@@ -0,0 +1,236 @@
+{
+    "description": "Caps Lock + b/c/d/f/g/l/m/n/o/p/s/t/w to open or switch to applications",
+    "manipulators": [
+        {
+            "from": {
+                "key_code": "g",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'ChatGPT'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "b",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Brave Browser'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "d",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Visual Studio Code'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "s",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Slack'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "l",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "key_code": "l",
+                    "modifiers": [
+                        "left_control"
+                    ]
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "t",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Ghostty'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "c",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Claude'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "w",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'WhatsApp Web'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "m",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -b 'net.whatsapp.WhatsApp'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "o",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Obsidian'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "f",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Finder'"
+                }
+            ],
+            "type": "basic"
+        },
+        {
+            "from": {
+                "key_code": "n",
+                "modifiers": {
+                    "mandatory": [
+                        "left_control",
+                        "left_shift",
+                        "left_option",
+                        "left_command"
+                    ]
+                }
+            },
+            "to": [
+                {
+                    "shell_command": "open -a 'Granola'"
+                }
+            ],
+            "type": "basic"
+        }
+    ]
+}

package/runtime/modules/karabiner/custom_delete_mapping.json

@@ -0,0 +1,13 @@
+{
+    "description": "Custom delete mappings",
+    "manipulators": [
+        {
+            "from": {
+                "key_code": "d",
+                "modifiers": { "mandatory": ["control"] }
+            },
+            "to": [{ "key_code": "delete_forward" }],
+            "type": "basic"
+        }
+    ]
+}

package/runtime/modules/karabiner/fn_to_control.json

@@ -0,0 +1,9 @@
+{
+    "description": "Remap Fn key to Left Control (built-in keyboard)",
+    "simple_modifications": [
+        {
+            "from": { "apple_vendor_top_case_key_code": "keyboard_fn" },
+            "to": [{ "key_code": "left_control" }]
+        }
+    ]
+}

package/runtime/modules/karabiner/install.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$ROOT_DIR/lib/common.sh"
+
+step "Installing Karabiner-Elements"
+
+if [[ "$PLATFORM" != "mac" ]]; then
+    warn "Karabiner-Elements is macOS only; skipping"
+    exit 0
+fi
+
+if command -v karabiner_cli &>/dev/null || [[ -d "/Applications/Karabiner-Elements.app" ]]; then
+    ok "Karabiner-Elements already installed"
+else
+    warn "Karabiner-Elements not found; installing via brew cask"
+    brew_install_cask karabiner-elements
+    ok "Karabiner-Elements installed"
+fi
+
+step "Installing karabiner config"
+
+CONFIG_DIR="$HOME/.config/karabiner"
+REPO_DEST="$CONFIG_DIR/karabiner_scripts"
+SRC_JSON="$SCRIPT_DIR/karabiner.json"
+DEST_JSON="$CONFIG_DIR/karabiner.json"
+
+mkdir -p "$CONFIG_DIR"
+
+warn "Quitting Karabiner-Elements briefly while syncing config"
+osascript -e 'tell application "Karabiner-Elements" to quit' 2>/dev/null || true
+pkill -x "Karabiner-Elements" 2>/dev/null || true
+pkill -f "karabiner_console_user_server" 2>/dev/null || true
+sleep 2
+
+backup_file "$DEST_JSON"
+
+if [[ "$SCRIPT_DIR" != "$REPO_DEST" ]]; then
+    step "Syncing repo copy to $REPO_DEST"
+    mkdir -p "$REPO_DEST"
+    rsync -a --delete --exclude='.git' "$SCRIPT_DIR/" "$REPO_DEST/"
+    ok "Repo synced"
+fi
+
+if [[ "$SRC_JSON" -ef "$DEST_JSON" ]]; then
+    ok "karabiner.json already linked to repo (live sync)"
+else
+    cp "$SRC_JSON" "$DEST_JSON"
+    ok "karabiner.json installed"
+fi
+
+open -a "Karabiner-Elements"
+ok "Karabiner-Elements relaunched"
+
+echo ""
+echo -e "  ${GRN}Done!${R} Karabiner-Elements is running with local repo config"
+echo -e "  ${D}Config: $SRC_JSON${R}"
+echo ""