shepherd-launcher/scripts

Shepherd Scripts System

This directory contains the unified script system for shepherd-launcher.

Quick Reference

# Main entry point
./shepherd --help

# Dependencies
./shepherd deps print build|run|dev
./shepherd deps install build|run|dev

# Building
./shepherd build [--release]

# Configuration
./shepherd config validate [path]

# Development
./shepherd dev run

# Installation
./shepherd install all --user USER [--prefix PREFIX]
./shepherd install bins [--prefix PREFIX]
./shepherd install config --user USER

# Hardening
./shepherd harden apply --user USER
./shepherd harden revert --user USER

Structure

scripts/
├── shepherd           # Main CLI dispatcher
├── dev                # Wrapper → shepherd dev run
├── admin              # Wrapper → shepherd install/harden
├── lib/               # Shared libraries
│   ├── common.sh      # Logging, error handling, sudo helpers
│   ├── deps.sh        # Dependency management
│   ├── build.sh       # Cargo build logic
│   ├── config.sh      # Configuration validation
│   ├── sway.sh        # Nested sway execution
│   ├── install.sh     # Installation logic
│   └── harden.sh      # User hardening/unhardening
└── deps/              # Package lists
    ├── build.pkgs     # Build-time dependencies
    ├── run.pkgs       # Runtime dependencies
    └── dev.pkgs       # Development extras

Design Principles

1. Single source of truth: All dependency lists are defined once in deps/*.pkgs
2. Composable: Each command can be called independently
3. Reversible: All destructive actions (hardening, installation) can be undone
4. Shared logic: Business logic lives in libraries, not duplicated across scripts
5. Clear separation: Build-only, runtime-only, and development dependencies are separate

Usage Examples

For Developers

# First time setup (installs system packages + Rust via rustup)
./shepherd deps install dev
./shepherd dev run

# Or use the convenience wrapper
./run-dev

For CI

# Install only build dependencies (includes Rust via rustup)
./shepherd deps install build

# Build release binaries
./shepherd build --release

For Production Deployment

# On a runtime-only system
sudo ./shepherd deps install run
./shepherd build --release
sudo ./shepherd install all --user kiosk --prefix /usr

# Optional: lock down the kiosk user
sudo ./shepherd harden apply --user kiosk

For Package Maintainers

# Print package lists for your distro
./shepherd deps print build > build-deps.txt
./shepherd deps print run > runtime-deps.txt

# Install with custom prefix and DESTDIR
make -j$(nproc)  # or equivalent
sudo DESTDIR=/tmp/staging ./shepherd install bins --prefix /usr

Dependency Sets

• build: Packages needed to compile the Rust code (GTK, Wayland dev libs, etc.) + Rust toolchain via rustup
• run: Packages needed to run the compiled binaries (Sway, GTK runtime libs)
• dev: Union of build + run + dev-specific tools (git, gdb, strace) + Rust toolchain

The dev set is computed as the union of all three package lists, automatically deduplicated.

Hardening

The hardening system makes reversible changes to restrict a user to kiosk mode:

# Apply hardening
sudo ./shepherd harden apply --user kiosk

# Check status
sudo ./shepherd harden status --user kiosk

# Revert all changes
sudo ./shepherd harden revert --user kiosk

All changes are tracked in /var/lib/shepherdd/hardening/<user>/ for rollback.

Applied restrictions:

• SSH access denied
• Console (TTY) login restricted
• Sudo access denied
• Shell restricted to Sway sessions only
• Home directory permissions secured

Adding New Dependencies

Edit the appropriate package list in deps/:

• deps/build.pkgs - Build-time dependencies
• deps/run.pkgs - Runtime dependencies
• deps/dev.pkgs - Developer tools

Format: One package per line, # for comments.

The CI workflow will automatically use these lists.