From fba5a37ef506aef3ba8c4975060eee44606f095f Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Tue, 20 Oct 2026 07:26:37 -0700 Subject: [PATCH 01/14] chore(asdf): add bun 1.4.3 to global tool versions Co-Authored-By: Claude Sonnet 5.5 --- .tool-versions | 1 + 1 file changed, 1 insertion(+) diff --git a/.tool-versions b/.tool-versions index acb17f9b..f8e41c43 100644 --- a/.tool-versions +++ b/.tool-versions @@ -6,3 +6,4 @@ golang 1.26.5 terraform 1.5.0 python 3.11.4 nim 2.0.8 +bun 1.4.3 From 8b4951a81a230fa256542ecdbe0a0d5722c92c48 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Wed, 28 Oct 2026 22:45:03 -0700 Subject: [PATCH 02/14] fix(observability): make stapler-squad dashboard mount path overridable Replace the stale hard-coded Linux path with STAPLER_SQUAD_DASHBOARDS_DIR, defaulting to $HOME/code/github.com/tstapler/stapler-squad/docs/observability/grafana/dashboards. Co-Authored-By: Claude Sonnet 5.5 --- stapler-scripts/observability/docker-compose.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stapler-scripts/observability/docker-compose.yml b/stapler-scripts/observability/docker-compose.yml index 4158f6cb..c18bb29c 100644 --- a/stapler-scripts/observability/docker-compose.yml +++ b/stapler-scripts/observability/docker-compose.yml @@ -93,8 +93,9 @@ services: # not here — bind-mounted directly so there's one copy, not two kept in # sync by hand. allowUiUpdates writes straight into that repo's working # tree; `git diff` there after a UI edit. See stapler-squad's - # docs/observability/README.md. - - /home/tstapler/Programming/stapler-squad/docs/observability/grafana/dashboards:/var/lib/grafana/dashboards/stapler-squad + # docs/observability/README.md. Override the checkout location with + # STAPLER_SQUAD_DASHBOARDS_DIR (e.g. a worktree or a non-default clone). + - ${STAPLER_SQUAD_DASHBOARDS_DIR:-${HOME}/code/github.com/tstapler/stapler-squad/docs/observability/grafana/dashboards}:/var/lib/grafana/dashboards/stapler-squad environment: - GF_SECURITY_ADMIN_USER=admin - GF_SECURITY_ADMIN_PASSWORD=admin From b46d5684976bfd40e8d6a06857807bcd00b2cf80 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Thu, 29 Oct 2026 18:42:47 -0700 Subject: [PATCH 03/14] feat(observability): add stapler-squad VCS status dashboard RED panels for GetVCSStatus: handler and git-computation latency percentiles, Connect error/cancel rate, error ratio, in-flight, cache and coalescing hit rate, slot queue wait. Queries verified against VictoriaMetrics through Grafana's /api/ds/query. Co-Authored-By: Claude Sonnet 5.5 --- .../dashboards/stapler-squad/vcs-status.json | 552 ++++++++++++++++++ 1 file changed, 552 insertions(+) create mode 100644 stapler-scripts/observability/grafana/dashboards/stapler-squad/vcs-status.json diff --git a/stapler-scripts/observability/grafana/dashboards/stapler-squad/vcs-status.json b/stapler-scripts/observability/grafana/dashboards/stapler-squad/vcs-status.json new file mode 100644 index 00000000..b2cbb780 --- /dev/null +++ b/stapler-scripts/observability/grafana/dashboards/stapler-squad/vcs-status.json @@ -0,0 +1,552 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": { + "type": "grafana", + "uid": "-- Grafana --" + }, + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "description": "GetVCSStatus health: handler latency, git computation time, error/cancel rate, cache and coalescing hit rate.", + "editable": true, + "refresh": "30s", + "schemaVersion": 39, + "time": { + "from": "now-6h", + "to": "now" + }, + "title": "stapler-squad: VCS status", + "uid": "ssq-vcs-status", + "tags": [ + "stapler-squad", + "vcs" + ], + "panels": [ + { + "id": 101, + "type": "row", + "title": "Golden signals: GetVCSStatus", + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 0 + } + }, + { + "id": 102, + "type": "timeseries", + "title": "GetVCSStatus handler latency (otelconnect)", + "description": "Server-side handler time as seen by otelconnect: excludes any browser-side queueing. Includes cache hits, so p50 is near zero. Uses increase() because otelconnect labels series with net_peer_port, so every new connection is a fresh series that rate() cannot see.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 1 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.5, sum(increase(rpc_server_duration_milliseconds_bucket{rpc_method=\"GetVCSStatus\"}[5m])) by (le))", + "legendFormat": "p50" + }, + { + "refId": "B", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.95, sum(increase(rpc_server_duration_milliseconds_bucket{rpc_method=\"GetVCSStatus\"}[5m])) by (le))", + "legendFormat": "p95" + }, + { + "refId": "C", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.99, sum(increase(rpc_server_duration_milliseconds_bucket{rpc_method=\"GetVCSStatus\"}[5m])) by (le))", + "legendFormat": "p99" + } + ], + "fieldConfig": { + "defaults": { + "unit": "ms", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 103, + "type": "timeseries", + "title": "Git computation latency (cache misses only)", + "description": "Wall time of one shared git status computation. A p99 near 30000 means the compute timeout is being hit.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 1 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.5, sum(rate(vcs_status_compute_duration_milliseconds_bucket{}[$__rate_interval])) by (le))", + "legendFormat": "p50" + }, + { + "refId": "B", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.95, sum(rate(vcs_status_compute_duration_milliseconds_bucket{}[$__rate_interval])) by (le))", + "legendFormat": "p95" + }, + { + "refId": "C", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.99, sum(rate(vcs_status_compute_duration_milliseconds_bucket{}[$__rate_interval])) by (le))", + "legendFormat": "p99" + } + ], + "fieldConfig": { + "defaults": { + "unit": "ms", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 104, + "type": "timeseries", + "title": "Error and cancel rate by Connect code", + "description": "Errors per 5m window by Connect code; canceled = caller left before git finished.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 0, + "y": 9 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(increase(rpc_server_duration_milliseconds_count{rpc_method=\"GetVCSStatus\",rpc_connect_rpc_error_code!=\"\"}[5m])) by (rpc_connect_rpc_error_code)", + "legendFormat": "{{rpc_connect_rpc_error_code}}" + } + ], + "fieldConfig": { + "defaults": { + "unit": "short", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 105, + "type": "timeseries", + "title": "Error ratio (alert-ready)", + "description": "Share of GetVCSStatus calls that returned a Connect error. Alert candidate: > 5% for 10m.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 8, + "y": 9 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(increase(rpc_server_duration_milliseconds_count{rpc_method=\"GetVCSStatus\",rpc_connect_rpc_error_code!=\"\"}[5m])) / sum(increase(rpc_server_duration_milliseconds_count{rpc_method=\"GetVCSStatus\"}[5m]))", + "legendFormat": "error ratio" + } + ], + "fieldConfig": { + "defaults": { + "unit": "percentunit", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + }, + "max": 1, + "min": 0 + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 106, + "type": "timeseries", + "title": "In-flight computations", + "description": "Git status computations running or waiting for one of 4 slots.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 16, + "y": 9 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(vcs_status_in_flight)", + "legendFormat": "running or queued" + } + ], + "fieldConfig": { + "defaults": { + "unit": "short", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 107, + "type": "row", + "title": "Caching and coalescing", + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 17 + } + }, + { + "id": 108, + "type": "timeseries", + "title": "Requests by outcome", + "description": "cache_hit, stale_hit (served stale, refresh in background), computed (leader), coalesced (joined a running computation), error, canceled.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 18 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(rate(vcs_status_requests_total[$__rate_interval])) by (outcome)", + "legendFormat": "{{outcome}}" + } + ], + "fieldConfig": { + "defaults": { + "unit": "reqps", + "custom": { + "lineWidth": 1, + "fillOpacity": 20, + "stacking": { + "mode": "normal", + "group": "A" + } + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 109, + "type": "timeseries", + "title": "Cache + coalesce hit rate", + "description": "Fraction of calls that did not start their own git computation.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 18 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(rate(vcs_status_requests_total{outcome=~\"cache_hit|stale_hit|coalesced\"}[$__rate_interval])) / sum(rate(vcs_status_requests_total[$__rate_interval]))", + "legendFormat": "avoided own git run" + }, + { + "refId": "B", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(rate(vcs_status_requests_total{outcome=\"coalesced\"}[$__rate_interval])) / sum(rate(vcs_status_requests_total[$__rate_interval]))", + "legendFormat": "coalesced only" + } + ], + "fieldConfig": { + "defaults": { + "unit": "percentunit", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + }, + "max": 1, + "min": 0 + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 110, + "type": "row", + "title": "Context", + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 26 + } + }, + { + "id": 111, + "type": "timeseries", + "title": "Wait for a computation slot", + "description": "Time a computation queued behind the 4-slot concurrency cap. Rising p95 means git load is saturating.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 27 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.5, sum(rate(vcs_status_queue_wait_duration_milliseconds_bucket{}[$__rate_interval])) by (le))", + "legendFormat": "p50" + }, + { + "refId": "B", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.95, sum(rate(vcs_status_queue_wait_duration_milliseconds_bucket{}[$__rate_interval])) by (le))", + "legendFormat": "p95" + }, + { + "refId": "C", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "histogram_quantile(0.99, sum(rate(vcs_status_queue_wait_duration_milliseconds_bucket{}[$__rate_interval])) by (le))", + "legendFormat": "p99" + } + ], + "fieldConfig": { + "defaults": { + "unit": "ms", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + }, + { + "id": 112, + "type": "timeseries", + "title": "Computation outcomes", + "description": "Result of each shared computation: ok, error, canceled, timeout.", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 27 + }, + "targets": [ + { + "refId": "A", + "datasource": { + "type": "prometheus", + "uid": "victoriametrics" + }, + "expr": "sum(rate(vcs_status_compute_duration_milliseconds_count[$__rate_interval])) by (result)", + "legendFormat": "{{result}}" + } + ], + "fieldConfig": { + "defaults": { + "unit": "ops", + "custom": { + "lineWidth": 1, + "fillOpacity": 0 + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "multi" + } + } + } + ] +} \ No newline at end of file From 632a8532e8fc184ca4f3c365d673c36a2a6fe044 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Fri, 30 Oct 2026 19:43:44 -0700 Subject: [PATCH 04/14] perf(zsh): fix macOS autofs /home spawn storm and speed up startup - Guard Linux-only /home/tstapler and /home/linuxbrew entries; on macOS /home is autofs, so every failed PATH lookup (~24ms) spawned od_user_homes (130-300/s), loading opendirectoryd and endpoint security. - Load zplug plugins statically (zplug on demand), cache completion output, single compinit -C, background keychain: interactive startup ~1.6s -> ~0.7s. Co-Authored-By: Claude Sonnet 5.5 --- .shell/exports.sh | 34 ++++++++++----- .shell/languages.sh | 2 +- .zprofile | 2 +- .zshrc | 103 ++++++++++++++++++++++++++++++++++---------- 4 files changed, 106 insertions(+), 35 deletions(-) diff --git a/.shell/exports.sh b/.shell/exports.sh index 2255843a..6252d848 100644 --- a/.shell/exports.sh +++ b/.shell/exports.sh @@ -7,6 +7,24 @@ pathadd() { fi } +# Print-and-cache for slow ` completion zsh` style generators: sets REPLY to a +# cache file keyed on the binary's mtime+size, so the tool only runs after an upgrade. +# zsh only (returns 1 elsewhere). Usage: _cache_output kubectl completion zsh && source "$REPLY" +_cache_output() { + [ -n "$ZSH_VERSION" ] || return 1 + local exe=${commands[$1]} dir=${XDG_CACHE_HOME:-$HOME/.cache}/shell-eval name=${(j:_:)@} + [[ -n $exe ]] || return 1 + local -A st + zmodload -F zsh/stat b:zstat && zstat -H st -- $exe || return 1 + REPLY=$dir/$name.${st[mtime]}-${st[size]} + [[ -s $REPLY ]] && return 0 + local -a stale + mkdir -p $dir && "$@" >| $REPLY.$$ 2>/dev/null && [[ -s $REPLY.$$ ]] && mv -f $REPLY.$$ $REPLY || { rm -f $REPLY.$$; return 1; } + stale=( $dir/$name.*(N) ); stale=( ${stale:#$REPLY} ) + (( $#stale )) && rm -f -- $stale + return 0 +} + # Add Rust/cargo-installed binaries (e.g. stapler-mcp, self-built rtk fork) to PATH pathadd "$HOME/.cargo/bin" @@ -102,7 +120,7 @@ fi export GIT_EDITOR=$EDITOR # Fixes git + gpg error inside of tmux -export GPG_TTY=$(tty) +export GPG_TTY=${TTY:-$(tty)} # Completions for NativeScript @@ -116,7 +134,7 @@ if hash hunspell 2>/dev/null; then fi if hash helm 2>/dev/null; then - source <(helm completion zsh) + _cache_output helm completion zsh && source "$REPLY" fi if hash aws_completer 2>/dev/null; then @@ -124,31 +142,27 @@ if hash aws_completer 2>/dev/null; then fi if hash aws-vault 2>/dev/null; then - eval "$(aws-vault --completion-script-zsh)" + _cache_output aws-vault --completion-script-zsh && source "$REPLY" export AWS_VAULT_BIOMETRICS=true fi if hash gr 2>/dev/null; then unalias gr 2>/dev/null - source <(gr completion) + _cache_output gr completion && source "$REPLY" fi if hash flux 2>/dev/null; then - source <(flux completion zsh) + _cache_output flux completion zsh && source "$REPLY" fi if hash kubectl 2>/dev/null; then - source <(kubectl completion zsh) + _cache_output kubectl completion zsh && source "$REPLY" fi # Add krew the kubectl plugin manager to path pathadd "${KREW_ROOT:-$HOME/.krew}/bin" -if hash helm 2>/dev/null; then - source <(helm completion zsh) -fi - pathadd "$HOME/.yarn/bin" pathadd "$HOME/.config/yarn/global/node_modules/.bin" pathadd "$HOME/.poetry/bin" diff --git a/.shell/languages.sh b/.shell/languages.sh index 86cf0e5a..69069cd5 100644 --- a/.shell/languages.sh +++ b/.shell/languages.sh @@ -35,7 +35,7 @@ if [ -f "$HOME/.rye/env" ]; then . "$HOME/.rye/env" fi -if [ -d /home/linuxbrew/.linuxbrew/bin ]; then +if [ "$(uname)" = Linux ] && [ -d /home/linuxbrew/.linuxbrew/bin ]; then eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv) fi diff --git a/.zprofile b/.zprofile index 228573e2..1a6ba1e1 100644 --- a/.zprofile +++ b/.zprofile @@ -4,4 +4,4 @@ # Added by Antigravity CLI installer -export PATH="/home/tstapler/.local/bin:$PATH" +[[ "$(uname)" == Linux ]] && export PATH="/home/tstapler/.local/bin:$PATH" # macOS /home is autofs: every PATH lookup spawns od_user_homes diff --git a/.zshrc b/.zshrc index 39673dd8..74cb4814 100644 --- a/.zshrc +++ b/.zshrc @@ -12,28 +12,83 @@ # inherits a dirty state. https://github.com/anthropics/claude-code/issues/10375 printf '\e[?1004l\e[?1000l\e[?1002l\e[?1003l\e[?1006l' -# Check if zplug is installed -if [[ ! -d ~/.zplug ]]; then - # Ignore the system .gitconfig in case it tries to force SSH - GIT_CONFIG_NOSYSTEM=1 git clone https://github.com/tstapler/zplug $HOME/.zplug -fi - - +# Plugins are sourced straight from the zplug checkout (~/.zplug/repos) in a +# fixed order instead of running `zplug check`/`zplug load` on every shell, +# which cost ~1s of forks and flock. Anything missing falls back to the full +# zplug flow below; `zplug` (install/update/...) is loaded on first use. export ZPLUG_LOADFILE=$HOME/.zplug_packages.zsh -source $HOME/.zplug/init.zsh - -# Install packages that have not been installed yet -if ! zplug check --verbose; then - printf "Install? [y/N]: " - if read -q; then - echo; zplug install - else - echo - fi +_zp=$HOME/.zplug/repos +_zp_plugins=( + $_zp/willghatch/zsh-hooks/zsh-hooks.plugin.zsh + $_zp/zsh-users/zsh-completions/zsh-completions.plugin.zsh + $_zp/Tarrasch/zsh-autoenv/autoenv.plugin.zsh + $_zp/zsh-users/zaw/zaw.plugin.zsh + $_zp/robbyrussell/oh-my-zsh/lib/completion.zsh + $_zp/robbyrussell/oh-my-zsh/plugins/kubectl/kubectl.plugin.zsh + $_zp/robbyrussell/oh-my-zsh/lib/functions.zsh + $_zp/robbyrussell/oh-my-zsh/plugins/aws/aws.plugin.zsh + $_zp/aswitalski/oh-my-zsh-sensei-git-plugin/sensei-git.plugin.zsh + $_zp/robbyrussell/oh-my-zsh/lib/git.zsh + $_zp/robbyrussell/oh-my-zsh/plugins/git/git.plugin.zsh + $_zp/djui/alias-tips/alias-tips.plugin.zsh + $_zp/robbyrussell/oh-my-zsh/plugins/asdf/asdf.plugin.zsh + $_zp/tarruda/zsh-autosuggestions/zsh-autosuggestions.plugin.zsh + $_zp/zsh-users/zsh-syntax-highlighting/zsh-syntax-highlighting.plugin.zsh + $_zp/zsh-users/zsh-history-substring-search/zsh-history-substring-search.plugin.zsh + $_zp/romkatv/powerlevel10k/powerlevel10k.zsh-theme + $_zp/romkatv/powerlevel10k/powerlevel9k.zsh-theme +) + +_zp_ok=1 +for _zp_file in $_zp_plugins; do [[ -r $_zp_file ]] || { _zp_ok=0; break; }; done + +if (( _zp_ok )); then + # Same ZSH/ZSH_CACHE_DIR zplug exports before loading oh-my-zsh files + export ZSH=$_zp/robbyrussell/oh-my-zsh ZSH_CACHE_DIR=$_zp/robbyrussell/oh-my-zsh/cache/ + path=($HOME/.zplug/bin $path) + fpath=($_zp/zsh-users/zsh-completions/src $ZSH/plugins/httpie $HOME/.zplug/misc/completions $fpath) + + # zplug exports these from .zplug_packages.zsh on every load + case $CPUTYPE in x86_64) ARCHITECTURE_NAME=amd64 ;; *) ARCHITECTURE_NAME=$CPUTYPE ;; esac + export ARCHITECTURE_NAME PLATFORM_ARCHITECTURE_GLOB="*${OSTYPE%%[-0-9.]*}*$ARCHITECTURE_NAME*" + + # One compinit: trust the dump (-C) and rebuild it at most once a day + autoload -Uz compinit + _zp_dump=( $HOME/.zplug/zcompdump(N.mh-24) ) + if (( $#_zp_dump )); then compinit -C -d $HOME/.zplug/zcompdump; else compinit -d $HOME/.zplug/zcompdump; fi + unset _zp_dump + + # zplug sent plugin stderr to its own log; keep shells quiet the same way + for _zp_file in $_zp_plugins; do source $_zp_file 2>/dev/null; done + setopt prompt_subst # zplug does this when loading a theme + + zplug() { + unfunction zplug + source $HOME/.zplug/init.zsh && zplug "$@" + } +else + # Check if zplug is installed + if [[ ! -d ~/.zplug ]]; then + # Ignore the system .gitconfig in case it tries to force SSH + GIT_CONFIG_NOSYSTEM=1 git clone https://github.com/tstapler/zplug $HOME/.zplug + fi + + source $HOME/.zplug/init.zsh + + # Install packages that have not been installed yet + if ! zplug check --verbose; then + printf "Install? [y/N]: " + if read -q; then + echo; zplug install + else + echo + fi + fi + + # Then, source plugins and add commands to $PATH + zplug load fi - -# Then, source plugins and add commands to $PATH -zplug load +unset _zp _zp_plugins _zp_ok _zp_file # Load the zshell mv module autoload -U zmv @@ -98,7 +153,7 @@ export ZPLUG_FILTER=fzy:fzf-tmux:fzf:peco:percol:zaw # pathadd is defined in ~/.shell/exports.sh (sourced below). -if [[ -x "/home/linuxbrew/.linuxbrew/bin/brew" ]]; then +if [[ "$(uname)" == Linux && -x "/home/linuxbrew/.linuxbrew/bin/brew" ]]; then eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" fi @@ -106,7 +161,9 @@ fi source $HOME/.shell/languages.sh if hash keychain 2>/dev/null; then - eval `keychain --quick --quiet --noask` + # Without --eval keychain prints nothing, so only its side effects matter + # (agent running, ~/.keychain/* refreshed): run it off the startup path. + keychain --quick --quiet --noask >/dev/null 2>&1 &! fi # Prompt Config @@ -149,4 +206,4 @@ esac # Added by Antigravity CLI installer -export PATH="/home/tstapler/.local/bin:$PATH" +[[ "$(uname)" == Linux ]] && export PATH="/home/tstapler/.local/bin:$PATH" # macOS /home is autofs: every PATH lookup spawns od_user_homes From a8705a922fc76323f99534ae8bc4f34fbd27c5bb Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Fri, 30 Oct 2026 22:08:31 -0700 Subject: [PATCH 05/14] perf(zsh): cut remaining startup forks; keep exports.sh bash-parseable - Answer the oh-my-zsh git plugin's `git version` from a cache keyed on the git binary instead of forking it every shell. - Drop `uname` forks on macOS (use $OSTYPE; .zshenv runs for every zsh). - Use ${UID} instead of `id -u`, and only look up the fallback SSH agent socket when the 1Password and GPG sockets are absent. - Move zsh-only _cache_output into .shell/cache-output.zsh (allowlisted in .gitignore): its `*(N)` glob made `bash -n .shell/exports.sh` fail, and .bashrc sources that file. bash gets a stub that returns 1. Co-Authored-By: Claude Sonnet 5.5 --- .gitignore | 1 + .shell/cache-output.zsh | 17 +++++++++++++++++ .shell/exports.sh | 33 ++++++++++++--------------------- .shell/languages.sh | 2 +- .zprofile | 2 +- .zshenv | 3 ++- .zshrc | 19 ++++++++++++++++--- 7 files changed, 50 insertions(+), 27 deletions(-) create mode 100644 .shell/cache-output.zsh diff --git a/.gitignore b/.gitignore index 4eb71ae4..69f0d201 100644 --- a/.gitignore +++ b/.gitignore @@ -245,6 +245,7 @@ secrets.fbg.op.sh.tpl # scripts. Any new file in .shell/ stays out of the repo until added here. .shell/* !.shell/aliases.sh +!.shell/cache-output.zsh !.shell/exports.sh !.shell/functions.sh !.shell/languages.sh diff --git a/.shell/cache-output.zsh b/.shell/cache-output.zsh new file mode 100644 index 00000000..96978054 --- /dev/null +++ b/.shell/cache-output.zsh @@ -0,0 +1,17 @@ +# Print-and-cache for slow ` completion zsh` style generators: sets REPLY to a +# cache file keyed on the binary's mtime+size, so the tool only runs after an upgrade. +# zsh-only syntax, kept out of exports.sh so bash can still parse that file. +# Usage: _cache_output kubectl completion zsh && source "$REPLY" +_cache_output() { + local exe=${commands[$1]} dir=${XDG_CACHE_HOME:-$HOME/.cache}/shell-eval name=${(j:_:)@} + [[ -n $exe ]] || return 1 + local -A st + zmodload -F zsh/stat b:zstat && zstat -H st -- $exe || return 1 + REPLY=$dir/$name.${st[mtime]}-${st[size]} + [[ -s $REPLY ]] && return 0 + local -a stale + mkdir -p $dir && "$@" >| $REPLY.$$ 2>/dev/null && [[ -s $REPLY.$$ ]] && mv -f $REPLY.$$ $REPLY || { rm -f $REPLY.$$; return 1; } + stale=( $dir/$name.*(N) ); stale=( ${stale:#$REPLY} ) + (( $#stale )) && rm -f -- $stale + return 0 +} diff --git a/.shell/exports.sh b/.shell/exports.sh index 6252d848..8784896b 100644 --- a/.shell/exports.sh +++ b/.shell/exports.sh @@ -7,23 +7,13 @@ pathadd() { fi } -# Print-and-cache for slow ` completion zsh` style generators: sets REPLY to a -# cache file keyed on the binary's mtime+size, so the tool only runs after an upgrade. -# zsh only (returns 1 elsewhere). Usage: _cache_output kubectl completion zsh && source "$REPLY" -_cache_output() { - [ -n "$ZSH_VERSION" ] || return 1 - local exe=${commands[$1]} dir=${XDG_CACHE_HOME:-$HOME/.cache}/shell-eval name=${(j:_:)@} - [[ -n $exe ]] || return 1 - local -A st - zmodload -F zsh/stat b:zstat && zstat -H st -- $exe || return 1 - REPLY=$dir/$name.${st[mtime]}-${st[size]} - [[ -s $REPLY ]] && return 0 - local -a stale - mkdir -p $dir && "$@" >| $REPLY.$$ 2>/dev/null && [[ -s $REPLY.$$ ]] && mv -f $REPLY.$$ $REPLY || { rm -f $REPLY.$$; return 1; } - stale=( $dir/$name.*(N) ); stale=( ${stale:#$REPLY} ) - (( $#stale )) && rm -f -- $stale - return 0 -} +# `_cache_output` (cached completion generators) uses zsh-only syntax, so it lives in +# cache-output.zsh; bash gets a stub that reports "no cache" and callers fall through. +if [ -n "$ZSH_VERSION" ]; then + source "$HOME/.shell/cache-output.zsh" +else + _cache_output() { return 1; } +fi # Add Rust/cargo-installed binaries (e.g. stapler-mcp, self-built rtk fork) to PATH pathadd "$HOME/.cargo/bin" @@ -179,15 +169,16 @@ export PATH="$PATH" # SSH agent priority: 1Password → GPG → ~/.ssh/agent/* fallback. # environment.d/ssh-agent.conf handles the systemd user instance (Claude Code, services). if [ -z "$SSH_AUTH_SOCK" ] || [ ! -S "$SSH_AUTH_SOCK" ]; then - _gpg_sock="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/gnupg/S.gpg-agent.ssh" + _gpg_sock="${XDG_RUNTIME_DIR:-/run/user/${UID:-$(id -u)}}/gnupg/S.gpg-agent.ssh" _op_sock="$HOME/.1password/agent.sock" - _fb_sock=$(ls -t "$HOME/.ssh/agent"/s.*.agent.* 2>/dev/null | head -1) if [ -S "$_op_sock" ]; then export SSH_AUTH_SOCK="$_op_sock" elif [ -S "$_gpg_sock" ]; then export SSH_AUTH_SOCK="$_gpg_sock" - elif [ -n "$_fb_sock" ] && [ -S "$_fb_sock" ]; then - export SSH_AUTH_SOCK="$_fb_sock" + else + # only fork for the newest fallback socket when the others are absent + _fb_sock=$(ls -t "$HOME/.ssh/agent"/s.*.agent.* 2>/dev/null | head -1) + [ -n "$_fb_sock" ] && [ -S "$_fb_sock" ] && export SSH_AUTH_SOCK="$_fb_sock" fi unset _gpg_sock _op_sock _fb_sock fi diff --git a/.shell/languages.sh b/.shell/languages.sh index 69069cd5..6b76173b 100644 --- a/.shell/languages.sh +++ b/.shell/languages.sh @@ -35,7 +35,7 @@ if [ -f "$HOME/.rye/env" ]; then . "$HOME/.rye/env" fi -if [ "$(uname)" = Linux ] && [ -d /home/linuxbrew/.linuxbrew/bin ]; then +if [ "${OSTYPE#linux}" != "$OSTYPE" ] && [ -d /home/linuxbrew/.linuxbrew/bin ]; then eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv) fi diff --git a/.zprofile b/.zprofile index 1a6ba1e1..d5225839 100644 --- a/.zprofile +++ b/.zprofile @@ -4,4 +4,4 @@ # Added by Antigravity CLI installer -[[ "$(uname)" == Linux ]] && export PATH="/home/tstapler/.local/bin:$PATH" # macOS /home is autofs: every PATH lookup spawns od_user_homes +[[ $OSTYPE == linux* ]] && export PATH="/home/tstapler/.local/bin:$PATH" # macOS /home is autofs: every PATH lookup spawns od_user_homes diff --git a/.zshenv b/.zshenv index 8af2a61f..cbe479f6 100644 --- a/.zshenv +++ b/.zshenv @@ -1,4 +1,5 @@ -OS=`uname -a` +# .zshenv runs for every zsh (scripts included): skip the uname fork on macOS +case $OSTYPE in darwin*) OS=Darwin ;; *) OS=`uname -a` ;; esac case $OS in '\1#-Microsoft') diff --git a/.zshrc b/.zshrc index 74cb4814..155b8b1b 100644 --- a/.zshrc +++ b/.zshrc @@ -58,8 +58,21 @@ if (( _zp_ok )); then if (( $#_zp_dump )); then compinit -C -d $HOME/.zplug/zcompdump; else compinit -d $HOME/.zplug/zcompdump; fi unset _zp_dump + # git.plugin.zsh forks `git version` on every shell (~0.26s under endpoint-security + # exec scans); answer it from a cache keyed on the git binary instead. + () { + local exe=${commands[git]} dir=${XDG_CACHE_HOME:-$HOME/.cache}/shell-eval; local -A st + [[ -n $exe ]] && zmodload -F zsh/stat b:zstat && zstat -H st -- $exe || return + local f=$dir/git-version.${st[mtime]}-${st[size]} + [[ -s $f ]] || { mkdir -p $dir && command git version >| $f 2>/dev/null || return; } + _zp_git_version=$(<$f) + git() { if [[ $1 == version ]]; then print -r -- $_zp_git_version; else command git "$@"; fi } + } + # zplug sent plugin stderr to its own log; keep shells quiet the same way for _zp_file in $_zp_plugins; do source $_zp_file 2>/dev/null; done + (( $+functions[git] )) && unfunction git + unset _zp_git_version setopt prompt_subst # zplug does this when loading a theme zplug() { @@ -153,7 +166,7 @@ export ZPLUG_FILTER=fzy:fzf-tmux:fzf:peco:percol:zaw # pathadd is defined in ~/.shell/exports.sh (sourced below). -if [[ "$(uname)" == Linux && -x "/home/linuxbrew/.linuxbrew/bin/brew" ]]; then +if [[ $OSTYPE == linux* && -x "/home/linuxbrew/.linuxbrew/bin/brew" ]]; then eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" fi @@ -190,7 +203,7 @@ if [[ "$WORKIVA" == true ]] ; then fi # By operating system -OS=$(uname -a) +: ${OS:=$(uname -a)} # normally already set by .zshenv case $OS in *Darwin*) source ~/.shell/osx.sh @@ -206,4 +219,4 @@ esac # Added by Antigravity CLI installer -[[ "$(uname)" == Linux ]] && export PATH="/home/tstapler/.local/bin:$PATH" # macOS /home is autofs: every PATH lookup spawns od_user_homes +[[ $OSTYPE == linux* ]] && export PATH="/home/tstapler/.local/bin:$PATH" # macOS /home is autofs: every PATH lookup spawns od_user_homes From ddbde6a3f4de6849135be395a2f8e342b9cadc50 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Fri, 30 Oct 2026 22:09:52 -0700 Subject: [PATCH 06/14] perf(git-hooks): share one origin lookup and skip redundant config writes Resolve origin once (GIT_HOOK_ORIGIN_URL) instead of re-running ls-remote in each hook and drop-in, and only write user.name/core.sshCommand when changed, since writes take the .git/config lock shared by every worktree. Co-Authored-By: Claude Sonnet 5.5 --- .gittemplates/hooks/pre-commit | 6 ++++++ .gittemplates/hooks/pre-push | 4 ++++ stapler-scripts/set_git_emails | 8 ++++++-- stapler-scripts/set_git_ssh | 6 +++--- 4 files changed, 19 insertions(+), 5 deletions(-) diff --git a/.gittemplates/hooks/pre-commit b/.gittemplates/hooks/pre-commit index 4a35d6a7..64212f86 100755 --- a/.gittemplates/hooks/pre-commit +++ b/.gittemplates/hooks/pre-commit @@ -1,5 +1,11 @@ #!/usr/bin/env sh +# Resolve origin once and share it: every `git` fork costs ~100s of ms under load, +# and set_git_emails plus each drop-in used to re-run `ls-remote` themselves. +# Drop-ins read ${GIT_HOOK_ORIGIN_URL-...} so they still work if run standalone. +GIT_HOOK_ORIGIN_URL=$(git ls-remote --get-url origin 2>/dev/null) +export GIT_HOOK_ORIGIN_URL + # Set the appropriate email based on repository $HOME/dotfiles/stapler-scripts/set_git_emails diff --git a/.gittemplates/hooks/pre-push b/.gittemplates/hooks/pre-push index c2586d8b..941a3d1d 100755 --- a/.gittemplates/hooks/pre-push +++ b/.gittemplates/hooks/pre-push @@ -1,5 +1,9 @@ #!/usr/bin/env sh +# Resolved once and shared with set_git_ssh and the drop-ins (one fork, not several). +GIT_HOOK_ORIGIN_URL=$(git ls-remote --get-url origin 2>/dev/null Date: Fri, 30 Oct 2026 22:09:52 -0700 Subject: [PATCH 07/14] chore(mcp): remove the playwright MCP server entry Co-Authored-By: Claude Sonnet 5.5 --- .config/mcp/mcp-servers.json | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/.config/mcp/mcp-servers.json b/.config/mcp/mcp-servers.json index 95e512ec..4e1b614c 100644 --- a/.config/mcp/mcp-servers.json +++ b/.config/mcp/mcp-servers.json @@ -21,17 +21,6 @@ "_requires": "Installed from tstapler/homebrew-tap by bootstrap-pyinfra and exposed through the stable ~/.local/bin path. Provides first-party session and compaction tools over stdio MCP.", "env": {} }, - "playwright": { - "command": "npx", - "args": [ - "-y", - "@playwright/mcp@latest", - "--config", - "${HOME}/.config/mcp/playwright-mcp-config.json" - ], - "_note": "--config forces headless + --disable-gpu: Chrome's GPU process was deterministically crashing (exit_code=139/SIGSEGV) in headed mode on this NVIDIA-driver machine, blocking browser automation (2026-09-07).", - "env": {} - }, "1password": { "command": "1password-mcp", "args": [], From 261d9b2c1e1a3ba1f473b7a16f9a49db96713913 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Fri, 30 Oct 2026 22:09:52 -0700 Subject: [PATCH 08/14] docs(skills): update playwright-skill Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/playwright-skill/SKILL.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.claude/skills/playwright-skill/SKILL.md b/.claude/skills/playwright-skill/SKILL.md index 853f7b8f..7d9a209f 100644 --- a/.claude/skills/playwright-skill/SKILL.md +++ b/.claude/skills/playwright-skill/SKILL.md @@ -393,6 +393,7 @@ For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFER - **Parameterize URLs** - Put detected/provided URL in a `TARGET_URL` constant at the top of every script - **DEFAULT: Visible browser** - Always use `headless: false` unless user explicitly asks for headless mode - **Headless mode** - Only use `headless: true` when user specifically requests "headless" or "background" execution +- **GPU acceleration** - Headed Chromium uses the GPU by default. Playwright's default headless mode (the headless shell) renders in software (SwiftShader), so for headless runs that need real GPU (WebGL, canvas, perf timing) launch with `channel: 'chromium'` (new headless) or add `args: ['--use-angle=metal', '--enable-gpu', '--ignore-gpu-blocklist']` (macOS; use `--use-angle=gl`/`vulkan` per platform). Don't pass `--disable-gpu` unless Chrome's GPU process crashes on that machine. Verify with CDP: `const { gpu } = await (await browser.newBrowserCDPSession()).send('SystemInfo.getInfo'); console.log(gpu.devices, gpu.featureStatus)` and look for `gpu_compositing: "enabled"` and a real device instead of SwiftShader (checked on Apple Silicon macOS: headed and `channel: 'chromium'` both report the Metal device; the default headless shell reports SwiftShader) - **Slow down:** Use `slowMo: 100` to make actions visible and easier to follow - **Wait strategies:** Use `waitForURL`, `waitForSelector`, `waitForLoadState` instead of fixed timeouts - **Error handling:** Always use try-catch for robust automation @@ -412,6 +413,19 @@ Ensure running from skill directory via `run.js` wrapper **Browser doesn't open:** Check `headless: false` and ensure display available +**Headed window renders only part of the page:** +A fixed `viewport` (or `setViewportSize`) larger than the actual window clips what the user sees. For +visible, user-driven sessions launch with `viewport: null` and `args: ['--start-maximized']` so the page +follows the window size (verified: switching from `viewport: { width: 1600, height: 1000 }` to this +rendered the full page). Keep explicit viewports for headless or screenshot-at-size runs. + +**Page behind SSO / login you can't script:** +Use `chromium.launchPersistentContext(profileDir, { headless: false, viewport: null, args: ['--start-maximized'] })` +with a private profile dir (`mkdir -m 700`), let the user sign in once in the window, and poll `page.url()` +until the app URL is reached before measuring. Reuse the same profile on later runs. To record traffic add +`recordHar: { path, content: 'omit' }` (keeps sizes/timings, drops bodies); the HAR still contains auth +headers, so keep it local and never print header values. + **Element not found:** Add wait: `await page.waitForSelector('.element', { timeout: 10000 })` From c33e8903c3cad58113d4df2f50fc693cd66adc31 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Fri, 30 Oct 2026 22:09:53 -0700 Subject: [PATCH 09/14] docs(claude): tighten comment guidance and sdd 6-verify skill (From the stash 'wip before pulling origin/master for pr-ship push'.) Co-Authored-By: Claude Sonnet 5.5 --- .claude/CLAUDE.md | 2 +- .claude/skills/sdd/skills/6-verify/SKILL.md | 25 ++++++++++++--------- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 298fed5f..534081f4 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -61,7 +61,7 @@ Use the serena MCP server for complex multi-file structural edits when available - **Self-explanatory code first.** A good name or a clean structure removes the need for a comment; reach for one only after that fails. - **Why, not what.** Comment a hidden constraint, a non-obvious tradeoff, or a workaround for a specific bug — never restate what the code already says. -- **Short beats long.** One line over a paragraph. If a comment needs more than a line, the code usually needs a rename instead. +- **Short beats long.** One line over a paragraph, and never more than 5 lines or one paragraph — the same ceiling `code:review`'s Code Quality check flags as MAJOR, so writing past it just means a reviewer sends it back. If a comment covers more than one distinct rationale (root cause vs. an accepted tradeoff vs. a pointer to a test), split it or cut to the single fact a reviewer would actually ask for — don't stack every consideration into one block. - **Docstrings on entry points only.** Give a public function or module an overview when its purpose isn't obvious from its name and signature; skip it for private helpers. - **Name assumptions and limits.** If a function assumes sorted input, a bounded range, or has a known failure mode, say so once at the point of use. diff --git a/.claude/skills/sdd/skills/6-verify/SKILL.md b/.claude/skills/sdd/skills/6-verify/SKILL.md index 6b68a9d1..f5f93e68 100644 --- a/.claude/skills/sdd/skills/6-verify/SKILL.md +++ b/.claude/skills/sdd/skills/6-verify/SKILL.md @@ -220,19 +220,24 @@ with the unresolved list. Do not proceed to . ### Layer 2 — Architecture & Design Quality (always two agents, regardless of technology) **Step 0: kibitzer mechanical pre-pass (optional, degrades gracefully)** - - If an MCP connection to `kibitzer` is available and the repo has a `.claude/inspect.json`: - call its `architecture_assessment` tool scoped (via `scope`) to the packages/modules - touched by the diff. If MCP isn't connected but `kibitzer` is on `PATH`, use the CLI - equivalent instead: `kibitzer run --trigger batch`. This is a mechanical - pre-pass, not a replacement for the architecture-review agent below — it covers what's - cheaply checkable (import cycles, layering violations, coupling thresholds, a Mermaid - dependency diagram via MCP, plus — if `.claude/inspect.json` declares + - `.claude/inspect.json` is NOT required — kibitzer's built-in checks (import cycles, + layering violations, coupling thresholds) run against any repo out of the box. The file + only adds optional custom rules on top (`architecture.components`/`dependency_rules`/ + `content_rules`/`naming_rules`) — treat its absence as "no custom rules," not "kibitzer + unavailable." + - If an MCP connection to `kibitzer` is available: call its `architecture_assessment` tool + scoped (via `scope`) to the packages/modules touched by the diff. If MCP isn't connected + but `kibitzer` is on `PATH`, use the CLI equivalent instead: `kibitzer run + --trigger batch`. This is a mechanical pre-pass, not a replacement for the + architecture-review agent below — it covers what's cheaply checkable (import cycles, + layering violations, coupling thresholds, a Mermaid dependency diagram via MCP, plus — + if `.claude/inspect.json` exists and declares `architecture.components`/`dependency_rules`/`content_rules`/`naming_rules` — cross-component dependency, content, and naming-convention violations), not qualitative judgment (SOLID, testability, over-engineering). - - If neither is reachable, or the repo has no `.claude/inspect.json`: skip this step - silently and proceed straight to the architecture-review agent with no pre-pass context. - Phase 6 must never fail or stall because kibitzer isn't set up. + - If kibitzer is neither MCP-connected nor on `PATH`: skip this step silently and proceed + straight to the architecture-review agent with no pre-pass context. Phase 6 must never + fail or stall because kibitzer isn't installed. - If it returns findings: pass its raw output (findings text + Mermaid diagram, if any) into the architecture-review agent's prompt below as grounding context. From b3b80cd396071b9f0d6e7a08b0b6f6000e033d58 Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Fri, 30 Oct 2026 22:09:53 -0700 Subject: [PATCH 10/14] feat(skills): add demo-assets and ui-html-mockup skills Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/demo-assets/SKILL.md | 115 ++++++++++++++++++ .claude/skills/ui-html-mockup/SKILL.md | 60 +++++++++ .../ui-html-mockup/assets/annotations.css | 19 +++ .../ui-html-mockup/assets/annotations.js | 74 +++++++++++ .../skills/ui-html-mockup/assets/shell.html | 67 ++++++++++ .claude/skills/ui-html-mockup/assets/tabs.js | 12 ++ .../skills/ui-html-mockup/scripts/probe.js | 28 +++++ .../skills/ui-html-mockup/scripts/probe.sh | 13 ++ .../skills/ui-html-mockup/scripts/shoot.sh | 8 ++ 9 files changed, 396 insertions(+) create mode 100644 .claude/skills/demo-assets/SKILL.md create mode 100644 .claude/skills/ui-html-mockup/SKILL.md create mode 100644 .claude/skills/ui-html-mockup/assets/annotations.css create mode 100644 .claude/skills/ui-html-mockup/assets/annotations.js create mode 100644 .claude/skills/ui-html-mockup/assets/shell.html create mode 100644 .claude/skills/ui-html-mockup/assets/tabs.js create mode 100644 .claude/skills/ui-html-mockup/scripts/probe.js create mode 100755 .claude/skills/ui-html-mockup/scripts/probe.sh create mode 100755 .claude/skills/ui-html-mockup/scripts/shoot.sh diff --git a/.claude/skills/demo-assets/SKILL.md b/.claude/skills/demo-assets/SKILL.md new file mode 100644 index 00000000..0817300c --- /dev/null +++ b/.claude/skills/demo-assets/SKILL.md @@ -0,0 +1,115 @@ +--- +name: demo-assets +description: "Capture and share demo assets on a GitHub PR: terminal-recording GIFs (vhs) and PNG screenshots, including browser screenshots of web pages (Playwright). Use for 'screenshots for the PR', 'demo gif', 'attach images/gifs to a PR', 'show the UI change'. Hosts files on a throwaway orphan branch deleted after merge" +allowed-tools: Bash(vhs:*) Bash(ffmpeg:*) Bash(git:*) Bash(gh:*) Bash(npx:*) Bash(node:*) +--- + +# Demo assets (GIFs and screenshots) for a PR comment + +Use when a PR needs visual evidence: a CLI/TUI flow (GIF) or a UI change (PNG). Posting is outward-facing: +draft the comment, get the user's approval before `gh pr comment`, and label it agent-authored if it goes out +under the user's login. + +**Rule: never commit assets into the PR branch.** They live only on the `qa-assets/pr-` branch (step 2). + +## 1a. Record a terminal GIF + +```sh +brew install vhs # pulls ttyd; runs headless +vhs demo.tape # tape: Output demo.gif / demo.mp4 +``` + +- Open the tape with a title card (PR number, scenarios shown) so the clip is self-describing. +- vhs drops frames at large sizes. Use `Set Framerate 12` and about 1500x860; a 1700x950 render of a 70s run came out 15s. +- Keep the GIF under ~5 MB: trim waits with `Sleep` and shorten timeouts via env overrides. Ship the MP4 too. +- Check it: `ffmpeg -ss 25 -i demo.mp4 -frames:v 1 f.png`, then look at a few frames. Don't claim it's legible unseen. + +## 1b. Capture PNG screenshots + +1. **List every page, tab and state the PR changes first** (including empty, error and loading states). One + image per state; tick each off before moving on. +2. Run the app locally, preferably against synthetic/fixture data. +3. Capture with Playwright (chromium) into `/tmp//`: + +```js +// shots.js — run: npx playwright install chromium && node shots.js +const { chromium } = require('playwright'); +(async () => { + const browser = await chromium.launch(); + const page = await browser.newPage({ viewport: { width: 1500, height: 1000 } }); + const shots = [['capacity', 'http://localhost:3000/capacity', '[data-testid=chart]']]; + for (const [name, url, ready] of shots) { + await page.goto(url); + await page.waitForSelector(ready); // wait for content, not a fixed sleep + await page.addStyleTag({ content: '*,*::before,*::after{animation:none!important;transition:none!important}' }); + await page.screenshot({ path: `/tmp/pr-assets/${name}.png` }); // viewport only; fullPage only if needed + } + await browser.close(); +})(); +``` + +- **Naming:** kebab-case, `[-].png`, e.g. `capacity.png`, `capacity-empty.png`. Names become + URLs; no spaces or uppercase. +- **Size:** viewport screenshots, not full-page, unless the page's point is its length. If installed, shrink + with `oxipng -o2 *.png` or `pngquant --force --ext .png 256 *.png`. +- **Look at every image** (Read the PNG) before publishing. Don't claim it's right unseen. +- **Sensitive data:** inspect each image for real hostnames, account IDs, emails, tokens, customer names or + internal URLs in the address bar, tabs or content. Prefer fixture data; otherwise re-capture or crop. In a + public repo anyone can see these files. + +## 2. Host on a throwaway orphan branch + +An orphan branch shares no history with the PR, so the PR diff and the default branch are untouched. + +```sh +git worktree add --orphan -b qa-assets/pr- /tmp/qa-assets- # git >= 2.42 +cp /tmp/pr-assets/*.png demo.gif demo.mp4 /tmp/qa-assets-/ # whichever you have +git -C /tmp/qa-assets- add . +git -C /tmp/qa-assets- commit -m "qa assets for PR (delete after merge)" +git -C /tmp/qa-assets- push origin qa-assets/pr- +git worktree remove /tmp/qa-assets- +``` + +Embed: + +```md + +![demo](https://raw.githubusercontent.com///qa-assets/pr-/capacity.png) + +![demo](https://github.com///raw/qa-assets/pr-/capacity.png) +``` + +For a GitHub Enterprise Server host, use `https://///raw/...` (there is no +`raw.githubusercontent.com`). + +## 3. Comment template + +```md +**Screenshots (agent-captured for this PR, not the author's own words)** + +| Page | Image | +|---|---| +| Capacity, default | ![capacity](/capacity.png) | +| Capacity, empty state | ![capacity-empty](/capacity-empty.png) | + +Demo: ![demo](/demo.gif) +``` + +Post it, then open the PR and confirm every image renders inline. If not, fall back to drag-and-drop upload in +the comment box and delete the branch. + +## 4. Clean up after merge + +```sh +git push origin --delete qa-assets/pr- +``` + +## Caveats + +- **Clones fetch it.** A default `git clone`/`git fetch` downloads every branch, so the blobs ride along for + everyone until the branch is deleted and the server garbage-collects. It is not checked out by default. + `--single-branch` clones skip it. Delete promptly. +- Anyone with read access sees the files, and in a public repo anyone does. Don't capture secrets or tokens. +- Branch protection or push rules matching `qa-assets/*` can block the push. +- The private-repo and GHES embed URLs are untested here; the render check is mandatory. +- Simplest alternative that leaves nothing in the repo: drag the files into the PR comment box by hand. diff --git a/.claude/skills/ui-html-mockup/SKILL.md b/.claude/skills/ui-html-mockup/SKILL.md new file mode 100644 index 00000000..034a7d7f --- /dev/null +++ b/.claude/skills/ui-html-mockup/SKILL.md @@ -0,0 +1,60 @@ +--- +name: ui-html-mockup +description: Build a shareable single-file HTML mockup of a UI redesign from real data, with Figma-style annotations (was/now/data/ask pins), a guided tour, a full state matrix and measured accessibility probes. Use when asked to prototype, mock up or critique a view and hand it to a partner team, or when a design needs evidence rather than opinion. +--- + +# UI HTML mockup + +A mockup is a single `.html` file, no build step, that runs from `file://`, shows real (trimmed) data, and explains how it differs from the current design. Anyone can open it, click the pins or take the tour, and answer the questions in it. + +## When to use + +- Redesigning or proposing a view and you need partner feedback. +- Critiquing an existing view: the mockup is the argument. +- Not for production code. Port to the real design system afterwards; this file uses raw colours on purpose. + +## Workflow + +1. **Name the question and the baseline.** Write the one question the page must answer ("which pools need attention?"). Capture the current design from screenshots or source and record what it does, so every "Was" is verified, not remembered. +2. **Get real data, read-only.** Prefer a snapshot of the real API over invented rows. Probe the API first: list the kinds or fields it serves, fetch one object, check size limits (responses over a gateway buffer fail outright; select fields to trim). Save raw responses outside the repo. Note what the API cannot provide; those become "Not available" notes and annotation questions, not fake numbers. +3. **Trim and anonymise.** Build a compact JSON (counts, states, timestamps). Drop names, IDs, UIDs and hostnames; use `Item #3 (omitted)`. Label the page as sample data. Keep snapshots from one point in time, because a busy system drifts between fetches and pages then disagree. +4. **Start from `assets/shell.html`.** Inline `annotations.css`, `tabs.js` and `annotations.js` at the placeholders (`/* ANNOTATIONS_CSS */`, `/* TABS_JS */`, `/* ANNOTATIONS_JS */`). Add pages as functions that return HTML from the data. Compute every on-screen number from the data so pages agree. +5. **Design the whole state matrix, not just the happy path.** Loading (skeleton), empty (reason plus next action), error (the real cause plus retry), stale (banner with timestamp; do not dim, dimming breaks contrast), no access (who can grant it). A State selector in the header switches them. +6. **Annotate.** For each part that differs from the current design add an entry: `type` (New, Changed, Question), `was` (current behaviour, verified), `now`, `data` (source field), `ask` (one question for the partner team). Order a `tour` of the most important entries across pages. +7. **Make it operable.** Real ` + * + * Share links: file.html#annotations, file.html#tour, file.html#. + */ +(function(){ + const M = window.MOCKUP; let on = false, pop = null, ti = -1; + const byId = id => M.annos.find(a => a.id === id); + const pageAnnos = () => M.annos.filter(a => a.page === '*' || a.page === M.getPage()); + const cls = a => a.type.toLowerCase(); + const html = a => `
${a.type}${a.title}
Was
${a.was}
Now
${a.now}
Data
${a.data}
Ask
${a.ask}
`; + function place(){ + const layer = document.getElementById('annoLayer'); layer.innerHTML = ''; + document.getElementById('annoPanel').style.display = on ? '' : 'none'; + document.getElementById('annoBtn').setAttribute('aria-pressed', on); + if (!on) return; + const list = pageAnnos(); + document.getElementById('annoCount').textContent = `(${list.length}, collapsed by default)`; + document.getElementById('annoList').innerHTML = list.map((a,i)=>`
  • ${a.type}
  • `).join(''); + list.forEach((a,i) => { const el = document.querySelector(a.sel); if (!el || !el.offsetParent) return; + const r = el.getBoundingClientRect(), b = document.createElement('button'); + b.className = 'pin ' + cls(a); b.textContent = i+1; b.dataset.id = a.id; b.setAttribute('aria-label', `Note ${i+1}, ${a.type}: ${a.title}`); + b.style.left = (r.left + scrollX - 12) + 'px'; b.style.top = (r.top + scrollY - 12) + 'px'; b.onclick = () => open(a.id); layer.appendChild(b); }); + } + // Place a floating card beside the highlighted element (right, left, below, above), choosing the spot with least overlap. + function placeNear(card, r){ + const W = card.offsetWidth, H = card.offsetHeight, m = 12, vw = innerWidth, vh = innerHeight; + const clamp = (x,y) => ({x:Math.min(vw-W-8, Math.max(8, x)), y:Math.min(vh-H-8, Math.max(8, y))}); + const overlap = p => Math.max(0, Math.min(p.x+W, r.right+6) - Math.max(p.x, r.left-6)) * Math.max(0, Math.min(p.y+H, r.bottom+6) - Math.max(p.y, r.top-6)); + const cands = [clamp(r.right+m, r.top), clamp(r.left-m-W, r.top), clamp(r.left, r.bottom+m), clamp(r.left, r.top-m-H)]; + let best = cands[0], bo = overlap(best); for (const c of cands) { const o = overlap(c); if (o < bo) { best = c; bo = o; } if (bo === 0) break; } + Object.assign(card.style, {left:best.x+'px', top:best.y+'px', bottom:'auto', transform:'none'}); + } + function popPlace(){ if (!pop) return; const a = byId(pop), el = document.querySelector(a.sel), p = document.getElementById('annopop'), s = document.getElementById('annoSpot'); if (!el || !p) return; + const r = el.getBoundingClientRect(); s.style.cssText = `left:${r.left-4}px;top:${r.top-4}px;width:${r.width+8}px;height:${r.height+8}px`; placeNear(p, r); } + function open(id, scroll){ close(); const a = byId(id), el = document.querySelector(a.sel); if (scroll && el) { el.scrollIntoView({block:'start'}); scrollBy(0,-70); } + setTimeout(() => { const p = document.createElement('div'); p.className = 'annopop'; p.id = 'annopop'; p.setAttribute('role','dialog'); p.setAttribute('aria-label', a.title); + p.innerHTML = html(a) + ''; document.body.appendChild(p); + const s = document.createElement('div'); s.id = 'annoSpot'; s.className = 'annospot'; document.body.appendChild(s); + pop = id; popPlace(); p.querySelector('button').focus(); }, 0); } + function close(){ document.getElementById('annopop')?.remove(); document.getElementById('annoSpot')?.remove(); pop = null; } + function toggle(v){ on = v ?? !on; close(); place(); } + function step(i){ if (i < 0 || i >= M.tour.length) return end(); ti = i; const a = byId(M.tour[i]); + if (a.page !== '*' && a.page !== M.getPage()) M.go(a.page); + M.before?.[a.id]?.(); + setTimeout(() => { const el = document.querySelector(a.sel); if (el) { el.scrollIntoView({block:'start'}); scrollBy(0,-70); } setTimeout(() => draw(a, i), 30); }, 30); } + function draw(a, i){ const el = document.querySelector(a.sel), r = el ? el.getBoundingClientRect() : {left:0,top:0,right:0,bottom:0,width:0,height:0}; + const had = document.getElementById('tourcard'), focusNext = !had || had.dataset.step !== String(i); + document.getElementById('tourLayer').innerHTML = `
    + `; + placeNear(document.getElementById('tourcard'), r); if (focusNext) document.getElementById('tournext').focus(); } + function start(){ close(); M.go(Object.keys(M.pages)[0]); step(0); } + function end(){ ti = -1; document.getElementById('tourLayer').innerHTML = ''; document.getElementById('tourBtn').focus(); } + document.addEventListener('keydown', e => { if (e.key==='Escape') { ti>=0 ? end() : pop && close(); } if (ti>=0 && e.key==='ArrowRight') step(ti+1); if (ti>=0 && e.key==='ArrowLeft') step(ti-1); }); + let raf = 0; const reflow = () => { cancelAnimationFrame(raf); raf = requestAnimationFrame(() => { if (ti>=0) draw(byId(M.tour[ti]), ti); popPlace(); }); }; + addEventListener('scroll', reflow, {passive:true}); addEventListener('resize', () => { place(); reflow(); }); + Object.assign(M, { afterRender: () => setTimeout(place, 0), toggle, open, close, start, step, end }); + const h = location.hash.replace('#','').split(/[&,]/); if (h.includes('annotations')) on = true; + const pg = h.find(x => M.pages[x]); if (pg) M.go(pg); + if (h.includes('tour')) setTimeout(start, 50); +})(); diff --git a/.claude/skills/ui-html-mockup/assets/shell.html b/.claude/skills/ui-html-mockup/assets/shell.html new file mode 100644 index 00000000..c43765f3 --- /dev/null +++ b/.claude/skills/ui-html-mockup/assets/shell.html @@ -0,0 +1,67 @@ + + + + +Mockup shell + + + + +
    + +

    Product · Mockup

    + + + +
    +
    +
    + + + + diff --git a/.claude/skills/ui-html-mockup/assets/tabs.js b/.claude/skills/ui-html-mockup/assets/tabs.js new file mode 100644 index 00000000..a528c444 --- /dev/null +++ b/.claude/skills/ui-html-mockup/assets/tabs.js @@ -0,0 +1,12 @@ +/* Arrow-key navigation for any role=tablist (ARIA tabs pattern, automatic activation). + * Markup:
    + * Give each tablist an id so focus can be restored after a re-render. Page switching between top-level pages is NOT a tablist: use + *