bin/README.md

# Utility Scripts Collection

> Comprehensive collection of bash utility scripts for various tasks

This repository contains a curated collection of bash scripts for repository management, color manipulation, documentation generation, artifact handling, and more.

## Table of Contents
- [`arty.sh`](#artysh) - Repository and Release Management
- [`artifact_github_download.sh`](#artifact_github_downloadsh) - GitHub Artifact Downloader
- [`artifact_postgres_export.sh`](#artifact_postgres_exportsh) - PostgreSQL Code Export
- [`css_color_filter.sh`](#css_color_filtersh) - CSS Filter Generator
- [`css_color_palette.sh`](#css_color_palettesh) - Color Palette Generator
- [`css_json_convert.sh`](#css_json_convertsh) - CSS Variable Converter
- [`doc_bash_generate.sh`](#doc_bash_generatesh) - Bash Documentation Generator
- [`doc_rust_generate.sh`](#doc_rust_generatesh) - Rust Documentation Generator
- [`jinja_template_render.sh`](#jinja_template_rendersh) - Jinja2 Template Renderer
- [`mime_mp4_gif.sh`](#mime_mp4_gifsh) - MP4 to GIF Converter

---

## `arty.sh`

**A bash library repository and release management system**

Combined functionality from arty.sh (repository management) and whip.sh (release cycle management).

### Usage

```bash
arty <command> [arguments] [--dry-run] [-v|--verbose]
```

### Commands

#### Repository Commands
- `install <repo-url> [name]` - Install a library from git repository
- `deps [--dry-run]` - Install all dependencies from arty.yml
- `list` - List installed libraries with dependency tree
- `remove <name>` - Remove an installed library
- `init [name]` - Initialize a new arty.yml project
- `source <name> [file]` - Source a library (for use in scripts)
- `exec <lib-name> [args]` - Execute a library's main script with arguments
- `<script-name>` - Execute a script defined in arty.yml

#### Release Commands
- `release [major|minor|patch]` - Full release workflow (default: patch)
  - Bumps version in arty.yml
  - Updates CHANGELOG.md from git history
  - Creates git commit
  - Creates and pushes git tag
- `version` - Show current version from arty.yml
- `bump <major|minor|patch>` - Bump version in arty.yml (no commit/tag)
- `changelog` - Generate changelog from git history
- `tag <version>` - Create and push git tag

#### Hook Commands
- `hooks install` - Install git commit hooks (includes shellcheck validation)
- `hooks uninstall` - Remove git commit hooks
- `hooks create` - Create default hook templates

#### Monorepo Commands
- `mono list [root] [pattern]` - List arty.yml projects
- `mono version [root] [pattern]` - Show versions of all projects
- `mono bump <type> [root] [pattern]` - Bump version for all projects
- `mono status [root] [pattern]` - Show git status for all projects
- `mono exec <cmd> [root] [pattern]` - Execute bash command on all projects
- `mono help` - Show detailed mono help

### Examples

```bash
# Repository Management
arty install https://github.com/user/bash-utils.git
arty deps
arty list

# Release Cycle
arty release                    # Patch release
arty release major              # Major version release
arty bump minor                 # Just bump version
arty hooks install              # Install commit hooks

# Monorepo Management
arty mono list                  # List all projects
arty mono version               # Show all project versions
arty mono exec "git status"     # Run command on all projects
```

---

## `artifact_github_download.sh`

**GitHub Artifact Downloader**

Download artifacts from GitHub Actions workflows with interactive selection or automatic matching.

### Usage

```bash
artifact_github_download.sh <REPO> [OPTIONS]
```

### Arguments
- `REPO` - GitHub repository (owner/repo)

### Options
- `-n, --name NAME` - Artifact name to download (preselect)
- `-o, --output DIR` - Output directory (default: current directory)
- `-h, --help` - Show help message

### Examples

```bash
# Interactive mode - list and select artifacts
artifact_github_download.sh valknarness/awesome

# Preselect artifact by name
artifact_github_download.sh valknarness/awesome -n awesome-database-latest

# Download to specific directory
artifact_github_download.sh valknarness/awesome -o ~/downloads
```

---

## `artifact_postgres_export.sh`

**Export code artifacts from Open WebUI PostgreSQL database**

Extract code artifacts from chat conversations stored in PostgreSQL, preserving directory structure and file names.

### Usage

```bash
artifact_postgres_export.sh [OPTIONS] <chat_id> <output_dir>
```

### Arguments
- `chat_id` - Chat ID from Open WebUI URL (UUID format)
- `output_dir` - Directory to save extracted code files

### Options
- `-H, --host HOST` - PostgreSQL host (default: ai_postgres via Docker)
- `-u, --user USER` - PostgreSQL user (default: ai)
- `-d, --db DATABASE` - PostgreSQL database (default: openwebui)
- `-v, --verbose` - Verbose output
- `--remote HOST` - SSH remote host for Docker access (default: vps)
- `-f, --force` - Force export even if output directory is not empty

### Features
- **Direct PostgreSQL access** via Docker exec (SSH-enabled for remote servers)
- **Automatic filename detection** from markdown headers
- **Directory structure preservation** - maintains original paths
- **Safety checks** - validates chat ID format and checks for empty output directory
- **Smart code extraction** - parses markdown code blocks with language detection
- **File extension mapping** - supports 20+ file types

### Examples

```bash
# Export chat to local directory
artifact_postgres_export.sh e135d74e-5b43-4b24-a651-e999f103942b ~/Projects/rust/piglet

# Export from remote server
artifact_postgres_export.sh --remote vps abc123def456 ./output

# Force export to non-empty directory
artifact_postgres_export.sh -f e135d74e-5b43-4b24-a651-e999f103942b ./output
```

---

## `css_color_filter.sh`

**CSS Color Filter Generator**

Generate CSS filter values to transform black elements into any target color using SPSA optimization.

### Usage

```bash
css_color_filter.sh [OPTIONS] [COLOR]
```

### Arguments
- `COLOR` - Hex color (e.g., #FF0000, ff0000) or RGB (e.g., 255,0,0)

### Options
- `-i, --interactive` - Interactive mode with colored preview
- `-r, --raw` - Output only the CSS filter (for piping)
- `-c, --copy` - Copy result to clipboard automatically
- `-h, --help` - Show help message

### Examples

```bash
css_color_filter.sh "#FF5733"
css_color_filter.sh ff5733
css_color_filter.sh "255,87,51"
css_color_filter.sh -i
```

### Algorithm
Uses SPSA (Simultaneous Perturbation Stochastic Approximation) to find optimal filter combinations that minimize color difference in RGB and HSL color spaces.

### Dependencies
- `bc` - For floating-point arithmetic
- `jq` - For JSON formatting (optional)

---

## `css_color_palette.sh`

**CSS Color Palette Generator (Pure Bash)**

Generate comprehensive color palettes without Node.js dependencies. Supports multiple harmony types and color scales.

### Usage

```bash
css_color_palette.sh COLOR [OPTIONS]
```

### Arguments
- `COLOR` - Base hex color (e.g., #3498db, 3498db)

### Options
- `-p, --palette TYPE` - Palette type: monochromatic, analogous, complementary, split-complementary, triadic, tetradic
- `-o, --output FILE` - Output file (default: ./colors.yaml)
- `-m, --mode MODE` - Color mode: light, dark (default: light)
- `-s, --style STYLE` - Style: shades, tints, tones, all (default: all)
- `-n, --name NAME` - Palette name (default: auto-generated)
- `--scales N` - Number of scale steps (default: 11)
- `-i, --interactive` - Interactive mode
- `-v, --verbose` - Verbose output with color preview

### Examples

```bash
css_color_palette.sh "#3498db"
css_color_palette.sh "#3498db" -p triadic -o palette.json
css_color_palette.sh "ff5733" -p analogous -m dark
```

### Dependencies
- `bc` - For floating-point arithmetic

---

## `css_json_convert.sh`

**CSS Variable to JSON/YAML Converter**

Extract CSS custom properties (variables) from a CSS file and convert them to JSON or YAML format.

### Usage

```bash
css_json_convert.sh [OPTIONS] <input.css>
```

### Arguments
- `<input.css>` - Input CSS file containing CSS variables

### Options
- `-o, --output FILE` - Output file path (default: ./output.yaml)
- `-c, --camel-case` - Convert variable names to camelCase
- `-v, --verbose` - Enable verbose output
- `-h, --help` - Show help message

### Examples

```bash
# Extract CSS vars to YAML (default)
css_json_convert.sh styles.css

# Extract to JSON with custom output
css_json_convert.sh styles.css -o theme.json

# Convert variable names to camelCase
css_json_convert.sh styles.css -o vars.json --camel-case
```

---

## `doc_bash_generate.sh`

**Bash Documentation Generator with Animated GIFs**

Generate comprehensive README.md files with embedded asciinema GIFs for bash scripts.

### Usage

```bash
doc_bash_generate.sh [OPTIONS] <executable> [executable...]
```

### Arguments
- `executable` - One or more executables or glob patterns

### Options
- `-o, --output FILE` - Output README.md path (default: ./README.md)
- `-t, --title TITLE` - Documentation title (default: auto-generated)
- `--no-gif` - Skip GIF generation (faster, text only)
- `--gif-only` - Only generate GIFs, don't update README
- `-h, --help` - Show help message

### Examples

```bash
doc_bash_generate.sh css_*.sh
doc_bash_generate.sh -o docs/README.md *.sh
doc_bash_generate.sh --title "My Awesome Tools" script1.sh script2.sh
```

### Dependencies
- `asciinema` - Terminal session recorder
- `agg` - Asciinema to GIF converter (cargo install agg)

---

## `doc_rust_generate.sh`

**Rust Documentation Generator with Custom Themes**

Generate beautiful Rust documentation with custom color schemes and styling.

### Usage

```bash
doc_rust_generate.sh [OPTIONS] <inputs...>
```

### Arguments
- `<inputs>` - Input file(s) or pattern(s) to document:
  - Rust project directories (containing Cargo.toml)
  - Individual .rs files
  - Markdown files (.md)
  - JSON/TOML configuration files
  - Glob patterns (e.g., src/**/*.rs)

### Options
- `-o, --output DIR` - Output directory for generated docs (default: $PWD/output)
- `-c, --color COLOR` - Primary accent color (hex format, default: #ff69b4)
- `-s, --style STYLE` - Background style theme: slate, zinc, neutral, stone, gray (default: slate)
- `--font-sans FONT` - Google Font for body text (default: Inter)
- `--font-mono FONT` - Google Font for code blocks (default: JetBrains Mono)
- `--serve` - Start HTTP server after generation
- `--open` - Open documentation in browser (implies --serve)
- `-p, --port PORT` - Port for HTTP server (default: 8000)
- `-v, --verbose` - Enable verbose output
- `-d, --dry-run` - Show what would be done without executing

### Examples

```bash
# Generate docs for current Rust project
doc_rust_generate.sh .

# Custom color scheme
doc_rust_generate.sh . -c "#3498db" -s zinc -o ./docs

# Document specific files
doc_rust_generate.sh src/lib.rs src/main.rs -o ./api-docs

# Use custom fonts
doc_rust_generate.sh . --font-sans "Roboto" --font-mono "Fira Code"

# Generate and open in browser
doc_rust_generate.sh . --open
```

### Dependencies
- cargo, rustdoc, bc, yq, jq, python3 with jinja2

---

## `jinja_template_render.sh`

**Jinja2 Template Renderer - Ninja Edition**

A sophisticated Jinja2 template rendering engine with support for multiple variable sources, glob patterns, and ninja-style operations.

### Usage

```bash
jinja_template_render.sh [OPTIONS] <template> [template...]
```

### Arguments
- `<template>` - Template file(s) to render (glob patterns supported)

### Options
- `-o, --output DIR` - Output directory (default: ./output)
- `-v, --var KEY=VALUE` - Define template variable (can be used multiple times)
- `-f, --file FILE` - Load variables from JSON/YAML file (repeatable)
- `-V, --verbose` - Enable verbose ninja commentary
- `-p, --preview` - Preview rendered output without saving
- `-s, --strict` - Enable strict mode (fail on undefined variables)
- `-d, --dry-run` - Perform dry run without writing files
- `-w, --watch` - Watch templates and re-render on changes (experimental)

### Examples

```bash
# Render single template with CLI variables
jinja_template_render.sh template.j2 -v name=Ninja -v level=Master

# Render multiple templates with YAML config
jinja_template_render.sh templates/*.j2 -f config.yaml -o dist/

# Render with multiple variable sources
jinja_template_render.sh app.j2 -f base.yaml -f env.json -v debug=true

# Preview without saving
jinja_template_render.sh template.j2 -f vars.yaml --preview --verbose
```

### Dependencies
- Python 3 with jinja2 package
- jq (for JSON parsing)
- yq (for YAML parsing)

---

## `mime_mp4_gif.sh`

**Advanced MP4 to GIF Converter**

Convert MP4 videos to animated GIFs with advanced frame extraction algorithms, interpolation functions, and magical effects.

### Usage

```bash
mime_mp4_gif.sh [OPTIONS] INPUT_FILE [OUTPUT_FILE]
```

### Arguments
- `INPUT_FILE` - Input MP4 video file (required)
- `OUTPUT_FILE` - Output GIF file (optional, defaults to INPUT_FILE.gif)

### Options
- `-k, --keyframes N` - Number of keyframes to extract (default: 10)
- `-d, --keyframe-duration MS` - Duration of each frame in milliseconds (default: 100, range: 1-30000)
- `-i, --input-schedules N` - Number of input schedules (default: 1)
- `-t, --transition TYPE` - Interpolation function for frame timing
  - Available: linear, sinoid, cubic, quadratic, exponential, bounce, elastic (default: linear)
- `-s, --schedule TYPE` - Algorithm to distribute keyframes across schedules
  - Available: uniform, front-load, back-load, center-peak, edge-peak, fibonacci, golden-ratio (default: uniform)
- `-m, --magic TYPE` - Apply magical effects to the GIF
  - Available: none, psychedelic, dither-bloom, edge-glow, temporal-blur, chromatic-shift, vaporwave (default: none)
- `-v, --verbose` - Enable verbose output

### Examples

```bash
# Basic conversion with 15 keyframes
mime_mp4_gif.sh -k 15 video.mp4

# Fast animation with 50ms per frame
mime_mp4_gif.sh -k 20 -d 50 video.mp4

# Use sinusoidal transition with center-peak distribution
mime_mp4_gif.sh -t sinoid -s center-peak -k 20 video.mp4

# Apply psychedelic magic with fibonacci distribution
mime_mp4_gif.sh -m psychedelic -s fibonacci -k 13 video.mp4 trippy.gif

# Complex: 3 schedules with cubic interpolation and edge glow
mime_mp4_gif.sh -i 3 -t cubic -s front-load -m edge-glow -k 30 video.mp4
```

---

## Installation

All scripts are available in this repository. Make sure they are executable:

```bash
chmod +x *.sh
```

Add them to your PATH for easy access:

```bash
export PATH="$PATH:/home/valknar/bin"
```

Or create symbolic links in `/usr/local/bin`:

```bash
sudo ln -s /home/valknar/bin/*.sh /usr/local/bin/
```

## Common Dependencies

Most scripts require:
- `bash` (4.0+)
- `bc` - For floating-point arithmetic
- `git` - For repository operations (arty.sh)
- `yq` - For YAML parsing (arty.sh)
- `jq` - For JSON parsing

Additional dependencies are listed in each command's help output.

## Contributing

Contributions are welcome! Please ensure:
- Scripts follow bash best practices
- Include comprehensive `--help` output with usage examples
- Test scripts before submitting

## License

MIT License - See individual scripts for details.

---

*Scripts collection maintained by valknar*