pbakaus/impeccable / .claude/skills/impeccable
impeccable
UnverifiedUse to design, redesign, critique, audit, polish or animate a frontend: websites, landing pages, dashboards, app UI, components, native iOS/Android screens, or a design system (DESIGN.md).
scripts/impeccable
View on GitHub#!/bin/sh
# Impeccable launcher. Runs the platform binary shipped next to this script:
# <this dir>/bin/<os>-<arch>/impeccable
# Order: $IMPECCABLE_BIN, the sibling binary, ~/.impeccable/bin/impeccable,
# the version-pinned cache, then `impeccable` on PATH. Never needs Node.
# The unversioned home binary and the PATH candidate are validated with the
# engine-probe handshake first: the retired 3.x npm CLI also installed a bin
# named `impeccable`, and exec'ing it would fail every verb with
# "Unknown command". The sibling binary must also report the version in
# VERSION: it is gitignored, so a skill upgrade that copies files over this
# directory leaves the old engine in place. A local build of the same version
# passes, which is why it is not hashed. IMPECCABLE_BIN is the operator's
# explicit choice and is exec'd without a probe. The version-pinned cache and
# the download are verified against engine-checksums.txt (next to this
# script), never against anything published beside the binary; a
# <binary>.verified stamp holding the manifest digest and the binary's size
# skips rehashing until either changes or the binary is newer than the stamp.
# No path hashes on every run: hooks run this launcher on every edit.
set -eu
# True when the candidate answers the engine handshake (prints
# "impeccable-engine <version>", exit 0). Quiet and fast (<100ms).
# IMPECCABLE_LAUNCHER_PROBE marks the child as a probe: a copy of this
# launcher reached recursively (e.g. symlinked onto PATH as `impeccable`)
# then skips its own probes and refuses to download, so probing stays cheap
# and can never loop.
probe_ok() {
probe_out=$(IMPECCABLE_LAUNCHER_PROBE=1 "$1" engine-probe 2>/dev/null) || return 1
case "$probe_out" in
impeccable-engine*) probe_version=${probe_out#impeccable-engine }; return 0 ;;
esac
return 1
}
probing=${IMPECCABLE_LAUNCHER_PROBE:-}
# Space, tab and CR, made once: hooks run this launcher on every edit and turn
# end, and every process it starts before the engine costs real time on a busy
# Windows machine (#1237), so the hot path below sticks to shell builtins.
ws=$(printf ' \t\r')
# Sets $digest_out to the digest engine-checksums.txt records for engine
# version $1 and asset $2 (lines are "<version> <asset> <sha256>"), empty when
# there is none.
# A CR is a separator too (CRLF checkouts), and a last line with no newline
# still counts.
manifest_digest() {
digest_out=""
[ -f "$manifest" ] || return 0
while IFS="$ws" read -r m_version m_asset m_sum _ || [ -n "$m_version" ]; do
case "$m_version" in ''|'#'*) continue ;; esac
if [ "$m_version" = "$1" ] && [ "$m_asset" = "$2" ]; then
digest_out=$m_sum
return 0
fi
done < "$manifest"
return 0
}
# Sets $expected (and, on Windows on ARM, which runs x64 binaries,
# $expected_x64) from engine-checksums.txt.
read_expected() {
manifest_digest "$version" "$asset"
expected=$digest_out
expected_x64=""
if [ "$os" = windows ] && [ "$arch" = arm64 ]; then
manifest_digest "$version" impeccable-windows-x64.exe
expected_x64=$digest_out
fi
}
# Sets $size to the byte count of the cached binary (BSD wc pads it).
cached_size() {
size=$(wc -c < "$cached") || size=""
size=${size##* }
}
# Sets $actual to the sha256 of $1, empty when no hash tool works.
hash_file() {
actual=""
if command -v shasum >/dev/null 2>&1; then
if digest=$(shasum -a 256 "$1" 2>/dev/null); then actual=${digest%% *}; fi
elif command -v sha256sum >/dev/null 2>&1; then
if digest=$(sha256sum "$1" 2>/dev/null); then actual=${digest%% *}; fi
fi
}
# This script's directory without dirname or a subshell: what dirname "$0"
# gives, made absolute by a cd there and back.
case $0 in
*/*) dir=${0%/*} ;;
*) dir=. ;;
esac
[ -n "$dir" ] || dir=/
caller_pwd=$PWD
CDPATH= cd -- "$dir" || { echo "impeccable: cannot enter the launcher directory $dir" >&2; exit 127; }
dir=$PWD
skill_dir=${dir%/*}
[ -n "$skill_dir" ] || skill_dir=/
cd -- "$caller_pwd" || { echo "impeccable: cannot return to $caller_pwd" >&2; exit 127; }
# VS Code syncs a plugin without the executable bit. Its hooks run this through
# sh, so restore the bit for the commands the skill runs directly (#1249).
[ -x "$0" ] || chmod +x "$0" 2>/dev/null || :
manifest="$dir/engine-checksums.txt"
# What the binary needs to know about its home: the skill directory (for
# reference/*.md and command-metadata.json) and how to name itself in the
# commands it prints. Exported BEFORE any exec below, including the
# IMPECCABLE_BIN override: an engine binary reached with no IMPECCABLE_SKILL_DIR
# cannot find reference/*.md (so native platform refs never inline) or read its
# own version (so UPDATE_AVAILABLE never fires). Setting it here covers every
# candidate the launcher can exec.
: "${IMPECCABLE_SKILL_DIR:=$skill_dir}"
: "${IMPECCABLE_SELF:=$0}"
export IMPECCABLE_SKILL_DIR IMPECCABLE_SELF
if [ -n "${IMPECCABLE_BIN:-}" ] && [ -x "${IMPECCABLE_BIN}" ]; then
exec "${IMPECCABLE_BIN}" "$@"
fi
# Windows names itself in the environment, which saves a process there; one
# uname covers the rest. PROCESSOR_ARCHITECTURE is what impeccable.cmd reads,
# so both launchers pick the same cached engine (AMD64 under x64 Git Bash on
# ARM64, as uname -m reported before).
if [ "${OS:-}" = Windows_NT ]; then
sys="Windows_NT ${PROCESSOR_ARCHITECTURE:-unknown}"
else
sys=$(uname -sm 2>/dev/null) || sys="unknown unknown"
fi
case "${sys%% *}" in
Darwin) os=darwin ;;
Linux) os=linux ;;
MINGW*|MSYS*|CYGWIN*|Windows_NT) os=windows ;;
*) os=unknown ;;
esac
case "${sys##* }" in
arm64|aarch64|ARM64) arch=arm64 ;;
x86_64|amd64|AMD64) arch=x64 ;;
*) arch=unknown ;;
esac
version=""
[ -f "$dir/VERSION" ] && { IFS="$ws" read -r version _ < "$dir/VERSION" || :; }
bin="$dir/bin/$os-$arch/impeccable"
[ "$os" = windows ] && bin="$bin.exe"
# Lost the executable bit in transit (zip extraction, some copiers).
if [ -f "$bin" ] && { [ -x "$bin" ] || chmod +x "$bin" 2>/dev/null; }; then
if [ -n "$probing" ] || [ -z "$version" ] || { probe_ok "$bin" && [ "$probe_version" = "$version" ]; }; then
exec "$bin" "$@"
fi
echo "impeccable: skipping $bin: it reports engine ${probe_version:-unknown} but this skill pins $version; delete it to stop this warning" >&2
fi
# On Windows (an MSYS/Git Bash shell) the cached names carry .exe so this
# launcher and impeccable.cmd share one cache.
exe=""
[ "$os" = windows ] && exe=".exe"
home_bin="${HOME:-/nonexistent}/.impeccable/bin/impeccable$exe"
if [ -z "$probing" ] && [ -x "$home_bin" ] && probe_ok "$home_bin"; then
exec "$home_bin" "$@"
fi
# Version-pinned user cache, filled by the download below or by `impeccable update`.
cache_root="${IMPECCABLE_HOME:-${HOME:-/nonexistent}/.impeccable}"
cached="$cache_root/bin/$version/impeccable$exe"
asset="impeccable-$os-$arch"
[ "$os" = windows ] && asset="$asset.exe"
if [ -n "$version" ] && [ -x "$cached" ]; then
read_expected
cached_size
stamp=""
stamp_size=""
{ IFS="$ws" read -r stamp stamp_size _ < "$cached.verified"; } 2>/dev/null || :
if [ -n "$stamp" ] && [ "$stamp_size" = "$size" ] && { [ "$stamp" = "$expected" ] || [ "$stamp" = "$expected_x64" ]; } && [ ! "$cached" -nt "$cached.verified" ]; then
exec "$cached" "$@"
fi
hash_file "$cached"
if [ -n "$actual" ] && { [ "$actual" = "$expected" ] || [ "$actual" = "$expected_x64" ]; }; then
{ echo "$actual $size" > "$cached.verified"; } 2>/dev/null || :
exec "$cached" "$@"
fi
echo "impeccable: cannot verify the cached engine $cached against $manifest; not using it" >&2
fi
if [ -z "$probing" ] && command -v impeccable >/dev/null 2>&1 && probe_ok impeccable; then
exec impeccable "$@"
fi
# Last resort: fetch this version's binary for the current platform from the
# public release channel into the user cache. Needs network; sandboxes without
# egress preinstall the binary on PATH instead.
setup_help() {
echo "Engine $version setup needs network access and write permission to $cache_root/bin/$version." >&2
echo "Run this launcher ($0) with engine-probe in a terminal that has those permissions, then retry the original command." >&2
echo "Alternatively, set IMPECCABLE_HOME to a writable cache location, or IMPECCABLE_BIN to a preinstalled engine binary." >&2
}
fetch_url() {
http_status=""
download_host=""
if command -v curl >/dev/null 2>&1; then
fetch_result=0
metadata=$(curl -fsSL --retry 2 -w '%{http_code} %{url_effective}' -o "$tmp" "$1" 2>/dev/null) || fetch_result=$?
http_status=${metadata%% *}
effective_url=${metadata#* }
# Only the authority is needed, never the signed storage URL's query.
download_host=${effective_url#*://}
download_host=${download_host%%/*}
download_host=${download_host##*@}
case "$download_host" in
\[*) download_host=${download_host%%]*}] ;;
*) download_host=${download_host%%:*} ;;
esac
download_host=$(printf '%s' "$download_host" | tr '[:upper:]' '[:lower:]')
return "$fetch_result"
elif command -v wget >/dev/null 2>&1; then
wget -q -O "$tmp" "$1" 2>/dev/null
else
return 1
fi
}
check_download() {
download_file=${1:-$tmp}
if [ ! -f "$download_file" ]; then
echo "impeccable: download completed but the file was removed before execution: $url; check your antivirus quarantine or logs. Refusing to continue; do not disable protection." >&2
exit 127
fi
if [ ! -s "$download_file" ]; then
rm -f "$download_file"
echo "impeccable: downloaded file is empty: $url; refusing the unverified download" >&2
exit 127
fi
}
if [ -n "$probing" ]; then
# Inside another launcher's probe: no download, fail fast and quiet.
exit 127
fi
if [ -n "$version" ] && [ "$os" != unknown ] && [ "$arch" != unknown ]; then
base="${IMPECCABLE_DOWNLOAD_BASE:-https://github.com/pbakaus/impeccable/releases/download}"
url="$base/engine-v$version/$asset"
read_expected
# Fail closed before any network traffic or cache write.
if [ -z "$expected" ] && [ -z "$expected_x64" ]; then
echo "impeccable: no checksum for engine $version ($asset) in $manifest; refusing the unverified download" >&2
exit 127
fi
tmp="$cache_root/bin/$version/.impeccable.part.$$"
# An interrupted download (Ctrl-C, a hook timeout) would otherwise leave the
# PID-named staging file behind for good. The handlers must exit explicitly.
cleanup() { rm -f "$tmp" 2>/dev/null || :; }
trap 'cleanup; exit 129' HUP
trap 'cleanup; exit 130' INT
trap 'cleanup; exit 143' TERM
if ! mkdir -p "$cache_root/bin/$version" 2>/dev/null; then
echo "impeccable: engine $version is not installed; cannot create cache directory: $cache_root/bin/$version" >&2
setup_help
exit 127
fi
# Check the actual staging file, not just directory existence: a cache from
# an earlier run can be readable but no longer writable inside a sandbox.
if ! (umask 077; : > "$tmp") 2>/dev/null; then
echo "impeccable: engine $version is not installed; cannot write to cache directory: $cache_root/bin/$version" >&2
setup_help
exit 127
fi
fetched=0
if [ -n "$expected" ] && fetch_url "$url"; then
fetched=1
elif [ -n "$expected_x64" ]; then
# Windows on ARM runs x64 binaries; fall back when no arm64 asset exists.
url="$base/engine-v$version/impeccable-windows-x64.exe"
expected=$expected_x64
fetch_url "$url" && fetched=1
fi
if [ "$fetched" = 1 ]; then
check_download
# No sha256 tool refuses the download too.
hash_file "$tmp"
check_download
if [ -z "$actual" ]; then
rm -f "$tmp"
echo "impeccable: cannot verify $url (no sha256 tool, or hashing failed); refusing the unverified download" >&2
exit 127
fi
if [ "$actual" != "$expected" ]; then
rm -f "$tmp"
echo "impeccable: checksum mismatch downloading $url" >&2
exit 127
fi
check_download
if ! chmod +x "$tmp" 2>/dev/null; then
check_download
rm -f "$tmp"
echo "impeccable: could not make the verified download executable: $url" >&2
exit 127
fi
check_download
if ! mv -f "$tmp" "$cached" 2>/dev/null; then
check_download
rm -f "$tmp"
echo "impeccable: could not cache the verified download: $url" >&2
exit 127
fi
check_download "$cached"
cached_size
{ echo "$actual $size" > "$cached.verified"; } 2>/dev/null || :
exec "$cached" "$@"
fi
rm -f "$tmp" 2>/dev/null
case "$http_status" in
5[0-9][0-9])
case "$download_host" in
github.com|*.github.com|githubusercontent.com|*.githubusercontent.com)
echo "impeccable: could not download engine $version: GitHub's downloads are failing right now (HTTP $http_status from $download_host). This is an outage on GitHub's side, not a problem with your setup or the CLI, so updating won't help. Check https://www.githubstatus.com and run the same command again once GitHub has recovered." >&2 ;;
*)
echo "impeccable: could not download engine $version: $download_host is failing right now (HTTP $http_status), a server error on $download_host's side. Try again later." >&2 ;;
esac
exit 127 ;;
esac
echo "impeccable: could not download engine $version from $url; check network access, the release URL, and curl or wget availability." >&2
setup_help
exit 127
fi
echo "impeccable: no engine binary for $os-$arch found (looked in $bin, $cached, PATH)." >&2
echo "Download impeccable-$os-$arch from https://github.com/pbakaus/impeccable/releases (tag engine-v$version) into $cache_root/bin/$version/impeccable$exe (then chmod +x), or set IMPECCABLE_BIN to a preinstalled engine binary. Docs: https://impeccable.style" >&2
exit 127
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |