skills.rest
pkirsanov
pkirsanovCOMMUNITY
Explore all skills by this author →
GitHub

bubbles-cross-platform-shell

Write shell scripts that run identically on GNU Linux and BSD macOS userlands.

1|Updated Mar 17, 2026
Search Tags:#shell scripting#bash#cross-platform#macos#portability#lint#gnu coreutils
One-click install
npx skills add https://github.com/pkirsanov/bubbles --skill bubbles-cross-platform-shell-pkirsanov
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bubbles-cross-platform-shell
Source: https://github.com/pkirsanov/bubbles/tree/main/skills/bubbles-cross-platform-shell
Command: npx skills add https://github.com/pkirsanov/bubbles --skill bubbles-cross-platform-shell-pkirsanov

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Shell scripts written with GNU coreutils flags (sed -i, date -d, stat -c, timeout, grep -P) abort or silently degrade on macOS, where the BSD userland behaves differently. This Skill provides portable helper functions, a pitfall-to-portable-form mapping table, and a mechanical lint guard so scripts run identically on both platforms. ## Core Features & Use Cases - Portable helper library: guard-lib.sh provides bubbles_sed_inplace, bubbles_iso_to_epoch, bubbles_now_ms, bubbles_file_mtime_epoch, and bubbles_run_with_timeout to replace GNU-only commands. - Pitfall reference table: maps 15+ GNU-only constructs (mktemp --suffix, readlink -f, paste -sd without stdin operand, awk 3-arg match) to forms that work on both userlands. - Mechanical enforcement: macos-portability-guard.sh lints caller-supplied script surfaces for 13 non-portable construct classes, with a # portable-ok pragma for intentional exceptions. - Use Case: A selftest fails on macOS with "sed: -i requires an argument" — use this Skill to route the edit through bubbles_sed_inplace and verify with the portability guard before pushing. ## Quick Start Review my shell script for GNU-only constructs and rewrite them using the portable guard-lib.sh helpers so it runs on both Linux and macOS.

Frequently Asked Questions about bubbles-cross-platform-shell

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write shell scripts that work on both Linux and macOS?▼

Avoid GNU-only flags and use portable helpers: bubbles_sed_inplace instead of sed -i, bubbles_iso_to_epoch instead of date -d, and bubbles_run_with_timeout instead of timeout. Detect tool capability rather than checking uname, and verify with shellcheck plus a BSD-userland run.

Why does sed -i fail on macOS with 'requires an argument'?▼

BSD sed requires a backup-extension argument after -i (sed -i ''), while GNU sed treats it as optional, making the two forms mutually incompatible. Use bubbles_sed_inplace from guard-lib.sh, which performs a temp-file rewrite that works on both.

How do I replace the timeout command on macOS?▼

macOS has no timeout command by default. Use bubbles_run_with_timeout, which tries timeout, then gtimeout from Homebrew coreutils, then a watchdog fallback, preserving exit code 124 on timeout.

Can I use readlink -f or realpath to get absolute paths on macOS?▼

No — BSD readlink lacks -f and canonicalizes symlinks differently (/var becomes /private/var). Preserve an already-absolute path verbatim instead of canonicalizing it, especially for checksummed or committed output.

How should selftests handle missing optional dependencies like PyYAML?▼

A selftest needing an optional dependency must print SKIP with the dependency name and exit 0 rather than hard-fail. Gate only the assertion, not the whole test, so a real regression on a fully provisioned machine still fails.

Does shellcheck catch GNU versus BSD portability issues?▼

No. shellcheck -x clean is necessary but not sufficient because it does not detect GNU/BSD runtime divergence. Use macos-portability-guard.sh, which lints for 13 non-portable construct classes, and verify on BSD userland or the PATH shim.

Related Skills

Explore More Software Engineering Skills→
program-the-brain-not-the-heartbeatprogram-the-brain-not-the-heartbeat

bash-script-validator

Validate Bash and POSIX shell scripts for syntax, security, and portability issues.

Community
Intermediate
SynkraAISynkraAI
3.1k

aiox-quality-gates

Runs lint, typecheck, test, and pre-push quality gates for AIOX projects.

Official
Basic
bismuthdigitalbismuthdigital

bash-review

Analyze bash scripts for security, error handling, quoting, and portability issues.

Official
Intermediate
DataDogDataDog
31

improve-test-coverage

Audits rshell's existing tests and generates new YAML scenario tests to improve coverage gaps identified from reference suites.

Official
Advanced