Initial implementation of breadpaper

CLI tool that sets a wallpaper with awww, generates a pywal colour
palette, and reloads bread-theme to recolour all running bread GTK apps.
Includes CI workflows, bakery metadata, and Arch PKGBUILD.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.forgejo/workflows/mirror.yml

@@ -0,0 +1,19 @@
+name: Mirror to GitHub
+
+on:
+  push:
+    branches: ['**']
+    tags: ['**']
+
+jobs:
+  mirror:
+    runs-on: [self-hosted, hestia]
+    steps:
+      - name: Mirror to GitHub
+        run: |
+          set -euo pipefail
+          git clone --mirror "https://git.breadway.dev/${GITHUB_REPOSITORY}.git" repo.git
+          cd repo.git
+          git push --prune \
+            "https://x-access-token:${{ secrets.MIRROR_TOKEN }}@github.com/Breadway/breadpaper.git" \
+            '+refs/heads/*:refs/heads/*' '+refs/tags/*:refs/tags/*'

.forgejo/workflows/package.yml

@@ -0,0 +1,37 @@
+name: Build and publish package
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  package:
+    runs-on: [self-hosted, hestia]
+    container:
+      image: archlinux:latest
+    steps:
+      - name: Build and publish
+        env:
+          PUBLISH_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          VERSION="${GITHUB_REF_NAME#v}"
+          pacman -Syu --noconfirm base-devel git rust cargo
+          useradd -m builder
+          git config --global --add safe.directory '*'
+          git clone --branch "${GITHUB_REF_NAME}" --depth 1 \
+            "https://git.breadway.dev/${GITHUB_REPOSITORY}.git" /home/builder/src
+          cd /home/builder/src
+          git archive --format=tar.gz --prefix="breadpaper-${VERSION}/" HEAD \
+            > packaging/arch/breadpaper-${VERSION}.tar.gz
+          SHA=$(sha256sum packaging/arch/breadpaper-${VERSION}.tar.gz | awk '{print $1}')
+          sed -i "s/^pkgver=.*/pkgver=${VERSION}/" packaging/arch/PKGBUILD
+          sed -i "s/^sha256sums=.*/sha256sums=('${SHA}')/" packaging/arch/PKGBUILD
+          chown -R builder:builder /home/builder/src
+          su builder -c "cd /home/builder/src/packaging/arch && makepkg -f --noconfirm --nocheck"
+          PKG=$(find /home/builder/src/packaging/arch -name '*.pkg.tar.zst' | head -1)
+          curl -fsS -X PUT \
+            -H "Authorization: token ${PUBLISH_TOKEN}" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@${PKG}" \
+            "https://git.breadway.dev/api/packages/Breadway/arch/os"

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: "-D warnings"
+
+jobs:
+  test:
+    name: fmt · clippy · test · build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Format check
+        run: cargo fmt --all -- --check
+
+      - name: Clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Test
+        run: cargo test --all --verbose
+
+      - name: Release build
+        run: cargo build --release --verbose

.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+env:
+  DL_DIR: /srv/breadway-dl
+  ECOSYSTEM_DIR: /home/breadway/Projects/bread-ecosystem
+
+jobs:
+  build:
+    runs-on: [self-hosted, hestia]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: build
+        run: cargo build --release --locked
+
+      - name: test
+        run: cargo test --release --locked
+
+      - name: prepare artifacts
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          PKG_DIR="${DL_DIR}/breadpaper/${VERSION}"
+          mkdir -p "${PKG_DIR}"
+          cp target/release/breadpaper "${PKG_DIR}/breadpaper-x86_64"
+          strip "${PKG_DIR}/breadpaper-x86_64"
+          sha256sum "${PKG_DIR}/breadpaper-x86_64" | awk '{print $1}' \
+            > "${PKG_DIR}/breadpaper-x86_64.sha256"
+          cp bakery.toml "${PKG_DIR}/bakery.toml"
+          ln -sfn "${VERSION}" "${DL_DIR}/breadpaper/latest"
+
+      - name: ensure bread-ecosystem
+        run: |
+          if [[ -d "${ECOSYSTEM_DIR}/.git" ]]; then
+            git -C "${ECOSYSTEM_DIR}" pull --ff-only
+          else
+            mkdir -p "$(dirname "${ECOSYSTEM_DIR}")"
+            git clone https://github.com/Breadway/bread-ecosystem.git "${ECOSYSTEM_DIR}"
+          fi
+
+      - name: regenerate index.json
+        run: bash "${ECOSYSTEM_DIR}/scripts/gen-index.sh"
+
+      - name: upload to GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          PKG_DIR="${DL_DIR}/breadpaper/${VERSION}"
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "breadpaper v${VERSION}" --generate-notes 2>/dev/null || true
+          gh release upload "${GITHUB_REF_NAME}" \
+            "${PKG_DIR}/breadpaper-x86_64" \
+            "${PKG_DIR}/breadpaper-x86_64.sha256" \
+            --clobber

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.lock

@@ -0,0 +1,193 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.102"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+
+[[package]]
+name = "breadpaper"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]

Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "breadpaper"
+version = "0.1.0"
+edition = "2024"
+description = "Wallpaper manager for the bread desktop"
+license = "MIT"
+
+[dependencies]
+clap = { version = "4", features = ["derive"] }
+anyhow = "1"

bakery.toml

@@ -0,0 +1,9 @@
+name = "breadpaper"
+description = "Wallpaper manager for the bread desktop — sets awww wallpaper, generates pywal palette, reloads bread themes"
+binaries = ["breadpaper"]
+system_deps = ["python-pywal"]
+optional_system_deps = ["awww"]
+bread_deps = ["bread"]
+
+[install]
+post_install = []

packaging/arch/PKGBUILD

@@ -0,0 +1,33 @@
+# Maintainer: Breadway <rileyhorsham@gmail.com>
+
+pkgname=breadpaper
+pkgver=0.1.0
+pkgrel=1
+pkgdesc="Wallpaper manager for the bread desktop"
+arch=('x86_64')
+url="https://github.com/Breadway/breadpaper"
+license=('MIT')
+options=(!lto !debug)
+depends=('glibc' 'python-pywal')
+optdepends=(
+  'awww: Wayland wallpaper daemon'
+)
+makedepends=('rust' 'cargo')
+source=("${pkgname}-${pkgver}.tar.gz")
+sha256sums=('SKIP')
+
+build() {
+  cd "${srcdir}/${pkgname}-${pkgver}"
+  cargo build --release --locked
+}
+
+check() {
+  cd "${srcdir}/${pkgname}-${pkgver}"
+  cargo test --release --locked
+}
+
+package() {
+  cd "${srcdir}/${pkgname}-${pkgver}"
+  install -Dm755 target/release/breadpaper "${pkgdir}/usr/bin/breadpaper"
+  install -Dm644 LICENSE "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE"
+}

src/lib.rs

@@ -0,0 +1,61 @@
+mod pywal;
+mod theme;
+mod wallpaper;
+
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result, bail};
+
+const IMAGE_EXTENSIONS: &[&str] = &["png", "jpg", "jpeg", "webp", "gif", "bmp"];
+
+pub fn set(path: &Path) -> Result<()> {
+    let path = validate(path)?;
+    apply_wallpaper(&path)?;
+    generate_palette(&path)?;
+    reload_theme()?;
+    Ok(())
+}
+
+pub fn get() -> Result<PathBuf> {
+    let home = std::env::var("HOME").context("HOME not set")?;
+    let wal_file = PathBuf::from(home).join(".cache/wal/wal");
+
+    let contents = std::fs::read_to_string(&wal_file)
+        .with_context(|| format!("no wallpaper set yet ({})", wal_file.display()))?;
+
+    Ok(PathBuf::from(contents.trim()))
+}
+
+pub fn apply_wallpaper(path: &Path) -> Result<()> {
+    wallpaper::apply(path)
+}
+
+pub fn generate_palette(path: &Path) -> Result<()> {
+    pywal::generate(path)
+}
+
+pub fn reload_theme() -> Result<()> {
+    theme::reload()
+}
+
+fn validate(path: &Path) -> Result<PathBuf> {
+    let canonical = path
+        .canonicalize()
+        .with_context(|| format!("not found: {}", path.display()))?;
+
+    let ext = canonical
+        .extension()
+        .and_then(|e| e.to_str())
+        .unwrap_or("")
+        .to_lowercase();
+
+    if !IMAGE_EXTENSIONS.contains(&ext.as_str()) {
+        bail!(
+            "unsupported file type '.{}' — expected one of: {}",
+            ext,
+            IMAGE_EXTENSIONS.join(", ")
+        );
+    }
+
+    Ok(canonical)
+}

src/main.rs

@@ -0,0 +1,36 @@
+use std::path::PathBuf;
+use std::process;
+
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(name = "breadpaper", about = "Wallpaper manager for the bread desktop")]
+struct Cli {
+    #[command(subcommand)]
+    command: Command,
+}
+
+#[derive(Subcommand)]
+enum Command {
+    /// Set wallpaper, generate pywal palette, and reload bread themes
+    Set {
+        /// Path to the image file
+        path: PathBuf,
+    },
+    /// Print the current wallpaper path
+    Get,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    let result = match cli.command {
+        Command::Set { path } => breadpaper::set(&path),
+        Command::Get => breadpaper::get().map(|p| println!("{}", p.display())),
+    };
+
+    if let Err(e) = result {
+        eprintln!("error: {e:#}");
+        process::exit(1);
+    }
+}

src/pywal.rs

@@ -0,0 +1,18 @@
+use std::path::Path;
+use std::process::Command;
+
+use anyhow::{Context, Result, bail};
+
+pub fn generate(path: &Path) -> Result<()> {
+    let status = Command::new("wal")
+        .arg("-i")
+        .arg(path)
+        .arg("-n") // skip wal's own wallpaper backend; awww already set it
+        .status()
+        .context("failed to run wal — is python-pywal installed?")?;
+
+    if !status.success() {
+        bail!("wal exited with {}", status);
+    }
+    Ok(())
+}

src/theme.rs

@@ -0,0 +1,15 @@
+use std::process::Command;
+
+use anyhow::{Context, Result, bail};
+
+pub fn reload() -> Result<()> {
+    let status = Command::new("bread-theme")
+        .arg("reload")
+        .status()
+        .context("failed to run bread-theme — is it installed?")?;
+
+    if !status.success() {
+        bail!("bread-theme reload exited with {}", status);
+    }
+    Ok(())
+}

src/wallpaper.rs

@@ -0,0 +1,17 @@
+use std::path::Path;
+use std::process::Command;
+
+use anyhow::{Context, Result, bail};
+
+pub fn apply(path: &Path) -> Result<()> {
+    let status = Command::new("awww")
+        .arg("set")
+        .arg(path)
+        .status()
+        .context("failed to run awww — is awww-daemon running?")?;
+
+    if !status.success() {
+        bail!("awww set exited with {}", status);
+    }
+    Ok(())
+}