Skip to content
Public template

About

A modular Rust boilerplate for building high-performance, cross-platform Liferay DXP CLI tools with automated multi-OS releases.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Liferay Rust Tool Template

A modular template for building high-performance, cross-platform CLI tools for Liferay DXP, Liferay Cloud (LXC), and Client Extensions.

New in v0.8.0

  • Bot Pull Requests: .github/rulesets/protect-main.json and a Repository Settings section set up the default branch the way liferay-docker-manager does: pull requests required with 0 approvals, squash only, no bypass actors, and GitHub Actions allowed to open pull requests.
  • no-issue-needed Label: Dependabot pull requests carry it, alongside the default dependencies and ecosystem labels.

New in v0.7.0

  • Version Gate: The release workflow rejects tags that don't match the Cargo.toml version, so --version always reports the released version.
  • --version Flag: The CLI exposes --version, and the Homebrew formula test checks it.
  • Distribution Fixes: The distribution prompt keeps formula.rb.example and scoop.json.example for future releases and skips Scoop updates the bucket already automates.

New in v0.6.0

  • Release Management & Changelog: Adopted release management architecture from ai-agent-template with CHANGELOG.md and automated release note extraction via scripts/release.py.
  • Dynamic Binary Derivation: Release workflows dynamically derive binary and asset names from Cargo.toml, removing template placeholders.
  • Doctor Verification Gate: Added scripts/doctor.py and pre-commit hook integration to guard against unreplaced placeholders.
  • Intel macOS Release Target: Cross-compiles x86_64-apple-darwin binaries on macos-latest runners alongside Apple Silicon.
  • Pinned Actions & Dependabot: All GitHub Actions pinned to immutable commit SHAs with automated weekly Dependabot updates.
  • Modernized Dependencies: Upgraded core and optional dependencies (reqwest 0.13, scraper 0.27, serde 1.0, clap 4.5, etc.).

Features

  • Cross-Platform: GitHub Actions pre-configured for Windows, Linux, and macOS (ARM/Intel).
  • Liferay Aware: Logic for path resolution and product version detection from gradle.properties.
  • Modern CLI: Built on clap for a professional command-line experience.

Project Structure

.
├── .cargo/config.toml        # Cargo aliases (lint, fmt-check)
├── .gemini/prompts/          # Automated Gemini CLI workflows
├── .github/
│   ├── dependabot.yml        # Automated dependency maintenance
│   ├── rulesets/             # Default branch protection (see Repository Settings)
│   └── workflows/            # Multi-OS CI/CD (Release, Rust)
├── .githooks/pre-commit      # Shared cross-platform git hook
├── scripts/
│   ├── doctor.py             # Placeholder verification gate
│   └── release.py            # Changelog extraction and tagging
├── src/
│   ├── main.rs               # Command routing
│   ├── core/
│   │   ├── mod.rs            # Core traits
│   │   └── env.rs            # Project discovery logic
│   ├── utils/
│   │   ├── mod.rs            # Utility re-exports
│   │   ├── git.rs            # Git wrappers
│   │   └── xml.rs            # Recursive XML logic
│   └── cli.rs                # Command definitions
├── CHANGELOG.md              # Keep a Changelog history
├── formula.rb.example        # Homebrew template
├── scoop.json.example        # Scoop template
├── .gitignore                # Tracks Cargo.lock for reliable CI
├── Cargo.toml                # Feature-based dependencies
└── LICENSE (MIT)

Prerequisites

  • Rust: cargo, rustc, rustfmt, clippy.
  • Git Hooks: To ensure consistent code style, activate the shared pre-commit hooks:
    • Run: git config core.hooksPath .githooks.
    • On macOS/Linux: chmod +x .githooks/pre-commit.
    • This hook automatically runs scripts/doctor.py, cargo fmt, and cargo clippy before each commit.

Getting Started

  1. Click "Use this template" on GitHub to create your new repository.
  2. Automated Initialization: Once cloned, ask Gemini to set up your new tool:
    "Please execute .gemini/prompts/setup-new-tool.md to initialize my new project"
    Gemini will automatically gather your project metadata (name, description, features) and update core configuration files (Cargo.toml and this README.md) for you. Release workflows automatically derive binary names directly from Cargo.toml.
  3. Manual Customization:
    • Customize subcommands in src/cli.rs.
    • Update LICENSE if necessary.
  4. First Release: Follow Releasing. Pushing a tag such as v0.1.0 builds and publishes binaries for all major operating systems.

Installation (End-Users)

Once a release is published and distribution channels are updated, users can install the tool using these commands:

Homebrew (macOS / Linux)

brew tap [github-user]/homebrew-tap
brew install [tool-name]

Scoop (Windows)

scoop bucket add [github-user] https://github.com/[github-user]/scoop-bucket
scoop install [tool-name]

Development

# Build locally
cargo build

# Run with arguments
cargo run -- --help

Repository Settings

Apply these once per new repository so that both people and bots change the default branch through pull requests, with no bypass actors:

REPO=[github-user]/[tool-name]

# Squash merges only, auto-merge on, and branches deleted after merge
gh api -X PATCH repos/$REPO -F allow_auto_merge=true -F delete_branch_on_merge=true \
  -F allow_squash_merge=true -F allow_merge_commit=false -F allow_rebase_merge=false

# Let GitHub Actions open pull requests
gh api -X PUT repos/$REPO/actions/permissions/workflow \
  -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true

# Label for pull requests that intentionally have no linked issue (Dependabot uses it)
gh label create no-issue-needed -R $REPO --color ededed \
  --description "PR intentionally has no linked issue (bot or trivial change)"

# Protect the default branch: pull request required, 0 approvals, squash only, linear history
gh api -X POST repos/$REPO/rulesets --input .github/rulesets/protect-main.json

A workflow that needs to change the default branch should push a dated branch, open a pull request, add the no-issue-needed label, and run gh pr merge --auto --squash.

Releasing

  1. Bump version in Cargo.toml and run cargo build to update Cargo.lock.
  2. Move the [Unreleased] entries in CHANGELOG.md into a new ## [x.y.z] - YYYY-MM-DD section.
  3. Commit, then create an annotated tag and push it:
    python3 scripts/release.py --tag vX.Y.Z
    git push origin vX.Y.Z
    The release workflow fails if the tag isn't annotated, doesn't match Cargo.toml, or has no CHANGELOG.md section.
  4. For a tool's first release, add it to the distribution channels (see below). After that, the Homebrew tap and Scoop bucket pick up new releases automatically within a couple of hours.

Distribution (macOS, Linux, Windows)

To avoid "Unidentified Developer" warnings on macOS and ensure a secure, user-level installation on Windows, we recommend building from source via Homebrew or Scoop.

Repository Visibility & Authentication

By default, Homebrew assumes your homebrew-tap and the tool's source repository are public.

If you wish to keep your distribution repositories private:

  1. Users must have a GitHub Personal Access Token (PAT) with repo scope.
  2. Users should export this token in their environment:
    export HOMEBREW_GITHUB_API_TOKEN=your_token_here
  3. Without a token, brew tap and brew install will fail for private repositories.

Automated Distribution via Gemini

This template includes an automated prompt for Gemini CLI to handle updating your Homebrew tap and Scoop bucket repositories with new releases.

Once a tool is in the tap and bucket, both update themselves from new GitHub releases, so this is only needed for a tool's first release. Ask Gemini:

"Please execute the steps in .gemini/prompts/update-distribution-channels.md to update my distribution repositories"

Gemini will automatically:

  1. Extract metadata from Cargo.toml.
  2. Calculate the SHA256 hash of the release tarball.
  3. Generate and write the Homebrew formula (formula.rb.example) and Scoop manifest (scoop.json.example).
  4. Commit and push the updates to your local homebrew-tap and scoop-bucket repositories.

Last Updated: 2026-11-11 | Last Reviewed: 2026-11-11

About

A modular Rust boilerplate for building high-performance, cross-platform Liferay DXP CLI tools with automated multi-OS releases.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages