diff --git a/README.md b/README.md index a621613..ed389ea 100644 --- a/README.md +++ b/README.md @@ -1,519 +1,68 @@ -# Utility Scripts Collection +# 🛠️ Pivoine Toolbelt -> Comprehensive collection of bash utility scripts for various tasks +A collection of sophisticated Bash utility scripts for creative automation, asset management, and infrastructure control. These tools are designed with a focus on aesthetics, usability, and seamless integration with the Pivoine ecosystem. -This repository contains a curated collection of bash scripts for repository management, color manipulation, documentation generation, artifact handling, and more. +## 🎨 Image & Creative Automation -## 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 +### `img_api_generate.sh` +The primary interface for the Pivoine Image Generation API. Supports high-performance image creation with advanced control parameters. + +* **Models:** `mystic`, `flux-dev`, `flux-pro`, `seedream`. +* **Features:** + * Custom aspect ratios (e.g., `square_1_1`, `widescreen_16_9`). + * Resolution control for Mystic model (1k, 2k, 4k). + * Seed reproducibility and styling injection. + * Integrated **FaceFusion** face swapping. + * Integrated **Real-ESRGAN** upscaling. +* **Usage:** `./img_api_generate.sh -p "a cinematic portrait of a neon cyborg" --aspect-ratio widescreen_16_9 -m flux-pro` + +### `css_color_palette.sh` +A zero-dependency color utility to generate comprehensive design tokens directly from the CLI. Generates tints, shades, and tones from a single base color. + +### `mime_mp4_gif.sh` +High-quality video-to-GIF conversion utility optimized for web performance and visual fidelity. --- -## `arty.sh` +## 📦 Asset & Model Management -**A bash library repository and release management system** +### `artifact_civitai_download.sh` & `artifact_huggingface_download.sh` +Streamlined downloaders for AI models (Checkpoints, LoRAs, VAEs). +* Manages a central cache. +* Automates symlinking to target application directories. +* Verification mode to ensure link integrity. -Combined functionality from arty.sh (repository management) and whip.sh (release cycle management). - -### Usage - -```bash -arty [arguments] [--dry-run] [-v|--verbose] -``` - -### Commands - -#### Repository Commands -- `install [name]` - Install a library from git repository -- `deps [--dry-run]` - Install all dependencies from arty.yml -- `list` - List installed libraries with dependency tree -- `remove ` - Remove an installed library -- `init [name]` - Initialize a new arty.yml project -- `source [file]` - Source a library (for use in scripts) -- `exec [args]` - Execute a library's main script with arguments -- `` - 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 ` - Bump version in arty.yml (no commit/tag) -- `changelog` - Generate changelog from git history -- `tag ` - 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 [root] [pattern]` - Bump version for all projects -- `mono status [root] [pattern]` - Show git status for all projects -- `mono exec [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_git_download.sh` & `artifact_github_download.sh` +Sophisticated wrappers for managing repository-based artifacts and binary releases. --- -## `artifact_github_download.sh` +## ⚡ Infrastructure & Services -**GitHub Artifact Downloader** +### `service_runpod_control.sh` +A beautiful CLI wrapper for managing RunPod GPU instances. Provides a unified interface for lifecycle management: +* `create`, `remove`, `start`, `stop`, `status`. -Download artifacts from GitHub Actions workflows with interactive selection or automatic matching. - -### Usage - -```bash -artifact_github_download.sh [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 -``` +### `jinja_template_render.sh` +Sophisticated Jinja2 template rendering engine. Ideal for generating configuration files, HTML emails, or boilerplate code using local JSON/YAML data. --- -## `artifact_postgres_export.sh` +## 🛠️ Developer Utilities -**Export code artifacts from Open WebUI PostgreSQL database** +* **`doc_bash_generate.sh`**: Automatic documentation generator for Bash scripts. +* **`doc_rust_generate.sh`**: Documentation helper for Rust projects. +* **`css_json_convert.sh`**: Bi-directional conversion between CSS variables and JSON objects. +* **`artifact_postgres_export.sh`**: Styled database export and snapshot utility. -Extract code artifacts from chat conversations stored in PostgreSQL, preserving directory structure and file names. +## 🚀 Getting Started -### Usage - -```bash -artifact_postgres_export.sh [OPTIONS] -``` - -### 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 -``` +1. **Dependencies**: Most scripts require `curl`, `jq`, and `base64`. +2. **API Tokens**: For API-reliant scripts (like `img_api_generate.sh`), ensure your token is set in `~/.config/pivoine/token` or via environment variables. +3. **Permissions**: Ensure scripts are executable: + ```bash + chmod +x *.sh + ``` --- - -## `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] -``` - -### Arguments -- `` - 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...] -``` - -### 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] -``` - -### Arguments -- `` - 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]