🪞 GUIHO Mirror

Open source project versioning for Bun, npm, JSR, and Git.

Mirror is a powerful, deterministic CLI for semantic project versioning. It reads a single version source, calculates the next semantic version, builds a transparent release plan, and safely applies it to configured outputs like package.json, jsr.json, and Git tags.

source -> version engine -> plan -> outputs

Mirror ships as a native Bun-compiled CLI binary. Direct installers run the native binary without requiring Node.js or Bun at runtime. Package-manager installs use a small Bun launcher with install-time and on-demand native binary download. Git is required only for Git-based workflows (source: "git", output: ["git"], or commit/tag/push operations).

---

🚀 Quick Start

Installation

npm install -D @guiho/mirror
# or
bun add -d @guiho/mirror

Direct native binary install on macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/CGuiho/mirror/main/mirror/install.sh | sh

Direct native binary install on Windows:

irm https://raw.githubusercontent.com/CGuiho/mirror/main/mirror/install.ps1 | iex

Initializing

Create a default configuration file for your project type:

mirror init package.json
# or
mirror init jsr.json
# or
mirror init git

Typical Workflow

# See current version
mirror version current

# Preview a patch release
mirror version plan patch

# Apply a minor release and create a Git commit & tag
mirror version apply minor --commit --yes

---

📖 Documentation

Mirror's architecture is based on a predictable read-plan-apply lifecycle, making it safe and easy to automate. It is designed to be easily consumed by humans and AI agents.

Project Model

Mirror uses a strict release model:

• Project: The package, repository, application, or directory being versioned.
• Source: The single adapter Mirror reads the current version from.
• Output: The adapters Mirror writes the next version to.
• Plan: The read-only description of all intended changes before any mutation occurs.

Adapters

Adapters connect Mirror to different versioning ecosystems:

• package.json: Reads/writes the version field in a package.json file.
• jsr.json: Reads/writes the version field in a jsr.json file.
• git: Reads versions from Git tags and creates release tags/commits. Requires Git to be installed and accessible in PATH.

CLI Commands

Mirror provides a concise CLI with three main command groups:

mirror init

Creates or reconciles a mirror.config.toml file in the current directory. On an interactive terminal, mirror init asks step-by-step questions (version source, outputs, package path, auxiliary paths, tag template, commit/push) with defaults you accept by pressing Enter. Pass flags to answer non-interactively, and in CI / non-TTY environments it uses flags + defaults without prompting.

• mirror init (interactive wizard, or flags + defaults when non-interactive)
• mirror init package.json / mirror init jsr.json / mirror init git (source shortcut)
• Flags: --source, --output, --package-file, --jsr-file, --auxiliary, --tag-template, --name, --preid, --commit, --push, --non-interactive, --yes

Defaults: source package.json, outputs package.json + git.

mirror config

Validates and inspects configuration.

• mirror config show: Prints the resolved configuration.
• mirror config check: Validates configuration without output.
• mirror config schema: Prints the comprehensive configuration reference. Use --format json to print a JSON Schema for editor autocomplete.

mirror agents

Installs Mirror-aware agent guidance for projects that use AI coding agents.

• mirror agents install local: Installs the bundled guiho-as-mirror skill at .agents/skills/guiho-as-mirror/SKILL.md.
• mirror agents install global: Installs the bundled guiho-as-mirror skill at ~/.agents/skills/guiho-as-mirror/SKILL.md.
• mirror agents instructions: Creates or updates AGENTS.md with the GUIHO Mirror semantic versioning section.

mirror version

Manages the version lifecycle.

• mirror version current: Prints the current project version.
• mirror version next <target>: Prints the next version without side-effects.
• mirror version plan <target>: Builds and prints the release plan.
• mirror version apply <target>: Applies the release plan.

Targets supported: major, premajor, minor, preminor, patch, prepatch, prerelease, or an exact semantic version (e.g., 2.0.0).

Configuration (mirror.config.toml)

Mirror looks for configuration via the --config <path> flag, ./mirror.config.toml, or ./config/mirror.config.toml.

schema = 1

[project]
name = "my-project"                    # Optional. Explicit project name.
name_source = "package.json"           # Optional. "package.json" or "jsr.json"

[version]
scheme = "semver"                      # Required. Only "semver" is supported.
source = "package.json"                # Required. "package.json", "jsr.json", or "git"
output = ["package.json", "git"]       # Required. Adapters to write to.
prerelease_id = "alpha"                # Optional. e.g., creates 1.0.1-alpha.0

[package]
path = "package.json"                  # Optional. Override path to package.json
auxiliary_paths = []                    # Optional. Extra package.json files that mirror the main version

[jsr]
path = "jsr.json"                      # Optional. Override path to jsr.json

[git]
tag_template = "{name}@{version}"      # Optional. Supported: "v{version}", "{name}@{version}", "{name}/v{version}"
commit = false                         # Optional. Create release commits. Default: false.
push = false                           # Optional. Push release refs. Default: false.
allow_dirty = false                    # Optional. Allow dirty Git worktree. Default: false.

[agents]
write_changelog = true                 # Optional. Tell agents changelog edits are allowed. Default: true.
changelog_path = "CHANGELOG.md"         # Optional. Changelog file path for agents. Default: "CHANGELOG.md".
auto_agents_md = true                  # Optional. Insert Mirror guidance into AGENTS.md when present. Default: true.
auto_skill_install = true              # Optional. Install guiho-as-mirror globally when missing. Default: true.

Agent Automation

Mirror is designed to be safely used by AI agents. Project commands automatically check for AGENTS.md and the guiho-as-mirror skill, then add the Mirror guidance or install the missing skill when automation is enabled. Running mirror with no arguments also performs this configured agent setup before showing help.

Set write_changelog = false when agents should skip changelog edits during release preparation. Set changelog_path = "docs/CHANGELOG.md" when the changelog is not at the project root. Set auto_agents_md = false to opt out of automatic guidance insertion, or auto_skill_install = false to opt out of automatic global skill installation.

Safety & Git Automation

By default, mirror version apply prevents accidental mutations:

• Fails on a dirty Git worktree (unless --allow-dirty is used).
• Requires --yes to skip interactive confirmation (non-interactive environments).
• Never pushes release refs automatically unless configured or --push is passed.

When combining file outputs (package.json, jsr.json) with Git tag output, Mirror requires either --commit or --push so that the tag attaches to the release commit containing the updated files. For Git-only outputs, --commit will not create an empty commit; it simply tags HEAD.

---

🛠️ Development

Development tasks require Bun. Run from the mirror/ directory:

cd mirror
bun install
bun run typecheck
bun test
bun run build
bun run binary

---

🎵 The Origin of the Name

The name Mirror was inspired by the music track "MIRROR" by SleepyThePrince & DJ Dadda, featured on the album "Blackout".

In a deeper sense, the name also fits the purpose of the library perfectly: just as looking in a mirror reflects an exact snapshot of who we are, this library reflects the exact state and version of whatever you are building.