ZFL (Zsh Function Library)

ZFL is a high-performance, modular configuration and function library for Zsh. While maintaining instant shell startup speeds (zero file-loading delay), it features non-blocking startup task scheduling, an AI-assisted development context packager, update detection, and various system utilities.

---

🚀 Core Features

• ⚡ Zero-Delay Startup (Lazy Loading)
  • Registers lightweight stubs for scripts under functions/ on startup. Code files are sourced only when the commands are actually executed.
  • Proxy completion loaders dynamically import complete autocomplete mappings on the first Tab trigger, maintaining both instant shell startups and complete autocomplete experiences.
• 🛡️ Non-Blocking Startup Tasks (FD 3 Isolation)
  • Reads and executes startup tasks through system file descriptor 3 (exec 3< ...), completely isolating them from standard stdin.
  • Prevents background interactive prompts from hijacking foreground stdin, resolving shell locking or crashing issues.
• 🤖 AI-Collaboration Friendly (AICP)
  • Built-in aicp tool packages codebase context under token budgets (fast/balanced/deep/full levels) and multi-dimensional filters.
  • Interactive --exec mode handles tool execution via XML tags, displaying source ranges and interactively applying unified diff patches upon user confirmation.
• 🔄 Lightweight Update Checks & One-Click Upgrade (check_update / update)
  • check_update performs zero-latency check of the last update date on shell startup and prompts if the reminder interval (customizable, default: 1 day) has passed, completely non-blocking and free of background scans.
  • Simply run update to upgrade system (Pacman/AUR via yay) and Flatpak packages in one go.
• 🔍 Static Quality Gates & Management (zfl)
  • Built-in zfl static code checker lints variable/file-descriptor leaks, naming styles, hardcoded colors, and missing documentation. Integrates with GitHub Actions gate checks.
  • Features a unified Metadata Engine Module (python/metadata_engine.py + core/metadata.zsh): single source of truth for parsing #? headers, alias canonicalization, and atomic zero-fork cache compilation.
  • Implements immutable core function protection and metadata #? protected: true safeguards, preventing built-in tools from accidental deletion.
  • Supports granular lazy loading prompt control via metadata tags (#? quiet: true) and environment variables (ZFL_LAZY_QUIET=1).
• 📦 Universal Decompression & One-Key Compression (extract)
  • Seamlessly handles multi-format archives (tar, gz, bz2, xz, zst, zip, 7z, rar) with built-in archive-bomb protection.
  • Supports --compress (-c) mode with parameter-driven format selection (--zip, --tar.gz, etc.) and rich Tab-completion descriptions.

---

📂 Project Structure

zsh/
├── base.zsh                          # Framework entry point (exports ZFL_HOME and loads core modules)
├── core/                             # Core dispatch and public modules
│   ├── colors.zsh
│   ├── func.zsh
│   ├── metadata.zsh
│   ├── startup_task_commands.zsh
│   ├── startup_tasks.zsh
│   ├── usr.zsh
│   └── usr.zsh.example
├── functions/                        # Modular function directory (1:1 mapping between file name and function name)
│   ├── add_task.zsh                  # Manage startup tasks list (whitelist management)
│   ├── aicp.zsh                      # Generate project context suitable for AI consumption (directory tree + file index + code snippet budget trimming)
│   ├── check_update.zsh              # Check last system update date and prompt update reminder
│   ├── countText.zsh                 # Count words or Chinese characters in a text file based on the specified mode
│   ├── extract.zsh                   # Universal auto-decompressor and compressor with format options, password encryption, compression stats, content listing, and Tab completion
│   ├── mskill.zsh                    # Manage, install, discover, package, update, and selectively link or copy AI Agent skills
│   ├── update.zsh                    # Update system packages (yay/pacman and flatpak)
│   ├── weather.zsh                   # Query real-time weather and weather forecast in terminal
│   └── zfl.zsh                       # ZFL framework built-in command line management and self-discovery tool
├── custom_functions/                 # User private local functions directory (ignored by git)
├── python/                           # Cross-language helper scripts
│   ├── aicp_context.py
│   ├── list_skills_fzf.py
│   ├── manage_skills.py              # Core management engine for AI Agent skills (Install, Discover, Package, Update, Status)
│   ├── metadata_engine.py            # ZFL Metadata Engine Module — Single Source of Truth for #? function metadata.
│   ├── preview_skill.py
│   ├── resolve_skills.py             # Parse and expand skill groups and skill names, and provide interfaces to manage groups
│   ├── skill_engine/                 # Unified skill lifecycle management internal package
│   └── zfl_lint.py
├── tests/                            # Automated unit test suite
│   ├── test_display.py               # Unit tests for skill_engine._display utilities.
│   ├── test_frontmatter.py           # Unit tests for skill_engine._frontmatter.
│   ├── test_groups.py                # Unit tests for skill_engine._groups.
│   ├── test_manage_skills_facade.py  # Unit tests for manage_skills unified dispatch facade.
│   ├── test_metadata_engine.py       # Unit tests for the ZFL Metadata Engine Module.
│   ├── test_mount.py                 # Unit tests for skill_engine._mount.
│   ├── test_repo.py                  # Unit tests for skill_engine._repo.
│   └── test_store.py                 # Unit tests for skill_engine._store.
├── docs/                             # Technical design, core mechanics, and troubleshooting documentation
│   ├── add_task.md                   # Non-blocking startup command and schedule scheduler.
│   ├── aicp.md                       # AI context packaging, token estimation, and interactive `--exec` loop helper.
│   ├── check_update.md               # Lightweight startup update reminder.
│   ├── countText.md                  # Characters and words counting tool for mixed English-Chinese texts.
│   ├── extract.md                    # Universal auto-decompressor with archive-bomb protection.
│   ├── fmt_novel.md
│   ├── mskill.md                     # Full-lifecycle AI Agent skills manager (install, package, update, unbind git, group, link, and copy).
│   ├── update.md                     # One-click system and Flatpak package updater.
│   ├── weather.md                    # Quick weather forecast query.
│   └── zfl.md                        # Built-in ZFL CLI manager and auto-discovery engine.
└── automation/                       # AI programming automation verification and sync scripts
    └── sync_readme.py                # Automatically synchronize and verify the README.md project structure tree

---

🛠️ Installation & Activation

1. Clone ZFL to your ~/.config/zsh directory:

   git clone https://github.com/Royikiss/zfl.git ~/.config/zsh

2. Append the following lines to your ~/.zshrc file to source ZFL:

   if [[ -f "$HOME/.config/zsh/base.zsh" ]]; then
       source "$HOME/.config/zsh/base.zsh"
   fi

3. Restart your terminal or run source ~/.zshrc to reload.

---

⚙️ Custom Configurations (core/usr.zsh)

To keep core framework files clean and avoid version control conflicts, core/usr.zsh is ignored by .gitignore and untracked.

Copy the template file to create your own configuration:

cp core/usr.zsh.example core/usr.zsh

Example configurations inside core/usr.zsh:

# User custom aliases
alias ls='eza --icons'
alias l='eza -lgh --header --git --icons'

# Network proxies
export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897

---

📖 Core Commands & Documentation

Each tool in ZFL has a companion markdown documentation under docs/. Click the links below to view details:

• ⚙️ zfl - Built-in ZFL CLI manager and auto-discovery engine.
• 🤖 aicp - AI context packaging, token estimation, and interactive --exec loop helper.
• 🔄 check_update - Lightweight startup update reminder.
• ⚡ update - One-click system and Flatpak package updater.
• ⚙️ add_task - Non-blocking startup command and schedule scheduler.
• 🧠 mskill - Full-lifecycle AI Agent skills manager (install, package, update, unbind git, group, link, and copy).
• 📊 countText - Characters and words counting tool for mixed English-Chinese texts.
• 📦 extract - Universal auto-decompressor with archive-bomb protection.
• 🌤️ weather - Quick weather forecast query.

---

🎨 Development Guidelines & Coding Standards

If you plan to contribute new tools or modify functions in ZFL, please adhere to the conventions defined in CONTRIBUTING.md and AGENTS.md:

1. File-to-Function 1:1 Mapping: New features must reside under functions/<name>.zsh containing exactly one entry function named <name>().
2. Metadata Header Standards: Include standardized metadata descriptions (lines starting with #?) declaring name, description, author, version, deps, usage, and optional control tags (quiet: true, protected: true) at the very top of files.
3. Strong Variable Declarations: All loop iterators, read buffers, and temporary variables must be explicitly declared as local to prevent namespace pollution.
4. Helper Function Cleanup: Out-of-scope helper functions must start with _parentname_ and be unloaded using unfunction before the parent exits. Embedded inner function structures are highly recommended.
5. FD 3 Safe Closing: Background tasks (&, coproc) or subshell forks must explicitly close file descriptor 3 (3<&-), preventing parent shells from hanging or locking.
6. No Hardcoded Colors: Use load_color instead of hardcoding ANSI escape codes. Declare CLI requirements at the top of functions using zfl_require.
7. Local Static Verification: Run zfl lint <name> and verify that it returns exit code 0 before committing changes.