mnenv 0.1.0 → 0.1.2

data/README.adoc

@@ -1,527 +1,270 @@
-= Metanorma Versions
+= mnenv
 
-image:https://img.shields.io/github/license/metanorma/versions[License]
-image:https://github.com/metanorma/versions/actions/workflows/rake.yml/badge.svg[Rake]
+image:https://img.shields.io/gem/v/mnenv.svg[RubyGems Version]
+image:https://img.shields.io/github/license/metanorma/mnenv.svg[License]
+image:https://github.com/metanorma/mnenv/actions/workflows/rake.yml/badge.svg["Build", link="https://github.com/metanorma/mnenv/actions/workflows/rake.yml"]
 
-Version discovery and management for Metanorma across multiple package sources.
+Version manager for Metanorma, similar to rbenv/pyenv.
 
 == Purpose
 
-This repository provides a unified interface for discovering and managing Metanorma versions from various sources:
+mnenv is a version manager for Metanorma that allows you to:
 
-* **Gemfile (Docker)** - Docker Hub images with Gemfile/Gemfile.lock.archived extraction
-* **Snap** - Snapcraft snap packages with revision tracking
-* **Homebrew** - macOS Homebrew formula versions from GitHub tags
-* **Chocolatey** - Windows Chocolatey packages
+* Install and manage multiple Metanorma versions
+* Switch between versions globally, per-project, or per-shell session
+* Install from multiple sources: RubyGems (gemfile) or pre-built binaries
 
-This enables link:{https://github.com/metanorma/actions-mn/setup}[actions-mn/setup] to provide version selection across all platforms.
-
-=== Historical Gemfile Lock Archive
-
-This repository also stores Gemfile and Gemfile.lock.archived files extracted from
-https://hub.docker.com/r/metanorma/metanorma[Docker Hub: metanorma/metanorma]
-Docker containers for each version of Metanorma.
-
-When deploying or using Metanorma, you may need to install the exact same gem
-versions that are used in a specific Docker container release. This repository
-provides the Gemfile and Gemfile.lock.archived files for each version of the
-metanorma/metanorma Docker image, allowing you to replicate the exact gem
-dependency set.
+Version data is sourced from the
+https://github.com/metanorma/versions[metanorma/versions] repository.
 
 == Features
 
-* *Unified CLI* - Single `mnenv` command to query and manage versions from all sources
-* *YAML Storage* - Version data stored in `data/` directory for easy inspection
-* *JSON Output* - CLI commands output JSON for GitHub Actions consumption
-* *Extraction Modes* - Incremental, replace, and revamp modes for Gemfile extraction
-* *Model-Driven OOP* - Built with lutaml-model for proper data serialization
+* *Multiple Installation Sources* - Install from RubyGems (gemfile) or pre-built binaries
+* *Version Switching* - Switch versions globally, per-project, or per-shell session
+* *Shell Integration* - Automatic PATH management via shims
+* *Cross-Platform* - Works on Linux, macOS, and Windows
+* *Offline Capable* - Version data cached locally for fast operation
 
-== Setting Up
+== Installation
 
-Clone this repository and install dependencies:
+=== As a Ruby gem
 
 [source,shell]
 ----
-git clone https://github.com/metanorma/versions.git
-cd versions
-bundle install
+gem install mnenv
 ----
 
-== Usage
-
-=== CLI commands
-
-The `mnenv` command provides subcommands for each platform:
+=== From source
 
 [source,shell]
 ----
-# List Gemfile (Ruby) versions
-bundle exec exe/mnenv gemfile list
-
-# List Snap versions
-bundle exec exe/mnenv snap list
-
-# List Homebrew versions
-bundle exec exe/mnenv homebrew list
-
-# List Chocolatey versions
-bundle exec exe/mnenv chocolatey list
-
-# List all versions in text format
-bundle exec exe/mnenv list-all
-
-# List all versions in JSON format
-bundle exec exe/mnenv list-all -f json
-
-# Get info for a specific version
-bundle exec exe/mnenv info gemfile 1.14.4
-
-# Show mnenv version
-bundle exec exe/mnenv version
+git clone https://github.com/metanorma/mnenv.git
+cd mnenv
+bundle install
+bundle exec rake install
 ----
 
-=== Updating version data
+=== Shell setup
 
-Each platform supports three modes of updating version data:
+After installation, add mnenv shims to your PATH:
 
-* *refresh* - Incremental mode: fetch only new versions not present locally
-* *revamp* - Re-fetch all versions, replacing existing data
-* *update VERSION* - Update a specific version
+==== Bash
 
-.Gemfile (Docker) updates
-[source,shell]
-----
-# Extract only missing versions (incremental mode)
-bundle exec exe/mnenv gemfile refresh
-
-# Replace a single version
-bundle exec exe/mnenv gemfile update 1.14.4
-
-# Re-extract all versions
-bundle exec exe/mnenv gemfile revamp
-----
+Add to `~/.bashrc`:
 
-.Snap updates
 [source,shell]
 ----
-# Fetch and add new Snap versions (preserves historical data)
-bundle exec exe/mnenv snap refresh
-
-# Update a specific Snap version (updates all arch/channel combinations)
-bundle exec exe/mnenv snap update 1.14.4
-
-NOTE: Snap does not support 'revamp' mode because historical revision data
-would be lost. The YAML file (data/snap/versions.yaml) is the single source
-of truth containing both historical Snapcraft revisions and current API data.
-----
-
-.Homebrew updates
-[source,shell]
+export PATH="$HOME/.mnenv/shims:$PATH"
 ----
-# Fetch and add new Homebrew versions
-bundle exec exe/mnenv homebrew refresh
 
-# Update a specific Homebrew version
-bundle exec exe/mnenv homebrew update 1.13.0
+==== Zsh
 
-# Re-fetch all Homebrew versions
-bundle exec exe/mnenv homebrew revamp
-----
+Add to `~/.zshrc`:
 
-.Chocolatey updates
 [source,shell]
 ----
-# Fetch and add new Chocolatey versions
-bundle exec exe/mnenv chocolatey refresh
-
-# Update a specific Chocolatey version
-bundle exec exe/mnenv chocolatey update 1.14.4
-
-# Re-fetch all Chocolatey versions
-bundle exec exe/mnenv chocolatey revamp
+export PATH="$HOME/.mnenv/shims:$PATH"
 ----
 
-.Extraction modes
-
-incremental:: Extract only versions that are not present locally. This is the default mode and is used for daily scheduled runs.
-
-replace:: Re-extract a single version, replacing any existing files. Use this to fix corrupted or outdated extractions.
-
-revamp:: Re-extract all versions, replacing all existing files. Use this when the data model changes or you need to refresh all versions.
-
-=== Ruby API
-
-Query versions programmatically:
+==== Fish
 
-[source,ruby]
-----
-require 'mnenv'
-
-# Gemfile versions
-gemfile_repo = Mnenv::GemfileRepository.new
-gemfile_versions = gemfile_repo.all
-gemfile_latest = gemfile_repo.latest
-
-# Snap versions
-snap_repo = Mnenv::SnapRepository.new
-snap_versions = snap_repo.all
-
-# Homebrew versions
-homebrew_repo = Mnenv::HomebrewRepository.new
-homebrew_versions = homebrew_repo.all
-
-# Chocolatey versions
-chocolatey_repo = Mnenv::ChocolateyRepository.new
-chocolatey_versions = chocolatey_repo.all
-----
-
-=== JSON output
-
-For GitHub Actions integration, output JSON format:
+Add to `~/.config/fish/config.fish`:
 
 [source,shell]
 ----
-bundle exec exe/mnenv list-all -f json
-----
-
-Returns:
-
-[source,json]
-----
-{
-  "gemfile": {
-    "count": 124,
-    "latest": "1.14.4",
-    "versions": [...]
-  },
-  "snap": {
-    "count": 14,
-    "latest": "1.14.4",
-    "versions": [...]
-  },
-  "homebrew": {
-    "count": 56,
-    "latest": "1.13.0",
-    "versions": [...]
-  },
-  "chocolatey": {
-    "count": 144,
-    "latest": "1.14.4",
-    "versions": [...]
-  }
-}
+set -gx PATH $HOME/.mnenv/shims $PATH
 ----
 
-== Direct Usage
+==== PowerShell (Windows)
 
-=== Reading version data from YAML files
+Add to your PowerShell profile:
 
-The version data is stored in YAML files under `data/` directory. You can read these files directly:
-
-[source,shell]
+[source,powershell]
 ----
-# View all Gemfile versions
-cat data/gemfile/versions.yaml
-
-# View all Snap versions with revisions
-cat data/snap/versions.yaml
-
-# View all Homebrew versions
-cat data/homebrew/versions.yaml
-
-# View all Chocolatey versions
-cat data/chocolatey/versions.yaml
+$env:PATH = "$env:USERPROFILE\.mnenv\shims;$env:PATH"
 ----
 
-.Parsing YAML with `yq`
+== Usage
+
+=== List available versions
 
 [source,shell]
 ----
-# Get the latest version from each source
-yq '.metadata.latest_version' data/gemfile/versions.yaml
-yq '.metadata.latest_version' data/snap/versions.yaml
-yq '.metadata.latest_version' data/homebrew/versions.yaml
-yq '.metadata.latest_version' data/chocolatey/versions.yaml
-
-# Get version count
-yq '.metadata.count' data/gemfile/versions.yaml
-
-# Get all version numbers
-yq '.versions[].version' data/gemfile/versions.yaml
-
-# Get specific version info (Snap example with revision)
-yq '.versions[] | select(.version == "1.14.4")' data/snap/versions.yaml
+mnenv install --list
+# or
+mnenv install -l
 ----
 
-.Parsing YAML with Ruby
+Shows all available Metanorma versions with platform availability:
 
-[source,ruby]
 ----
-require 'yaml'
+Available Metanorma versions:
+(gemfile = source build, binary = prebuilt for specific platforms)
 
-# Load Gemfile versions
-data = YAML.load_file('data/gemfile/versions.yaml')
-puts "Latest: #{data['metadata']['latest_version']}"
-puts "Count: #{data['metadata']['count']}"
+  1.14.4         (gemfile, binary [linux, macos*, windows])
+  1.14.3         (gemfile, binary [linux, macos*, windows])
+  1.14.1         (binary [linux, macos*])
+  ...
 
-# Find specific version
-version_1_14_4 = data['versions'].find { |v| v['version'] == '1.14.4' }
+Legend:
+  * Current version / platform
+  [installed: ...] = Already installed locally
+  Detected platform: macos
 ----
 
-=== CLI queries for specific use cases
+=== Install a version
 
 [source,shell]
 ----
-# Get the latest version across all sources
-bundle exec exe/mnenv list-all -f json | jq -r '.[].latest'
+# Install from gemfile (source build, requires dev tools)
+mnenv install 1.14.4 --source gemfile
 
-# Check if a specific version exists in Snap
-bundle exec exe/mnenv snap list | grep "1.14.4"
+# Install from binary (pre-built, no dev tools needed)
+mnenv install 1.14.4 --source binary
 
-# Get Snap revision for a specific version/arch
-bundle exec exe/mnenv snap list | grep "1.14.4" | grep "amd64"
+# Interactive installation
+mnenv install -i
 
-# List all versions newer than 1.10.0
-bundle exec exe/mnenv gemfile list | awk '/v1\.(1[4-9]|[2-9][0-9])/ {print}'
-
-# Count versions per source
-bundle exec exe/mnenv gemfile list | wc -l
-bundle exec exe/mnenv snap list | wc -l
+# List versions before installing
+mnenv install --list
 ----
 
-=== Using version data in scripts
-
-.Bash script to check for new versions
+=== List installed versions
 
 [source,shell]
 ----
-#!/bin/bash
-# check_versions.sh - Check if a version exists across all sources
-
-VERSION=$1
-
-if [ -z "$VERSION" ]; then
-  echo "Usage: $0 <version>"
-  exit 1
-fi
-
-echo "Checking version $VERSION across all sources..."
-
-# Check Gemfile
-if bundle exec exe/mnenv gemfile list | grep -q "$VERSION"; then
-  echo "✓ Gemfile: $VERSION found"
-else
-  echo "✗ Gemfile: $VERSION not found"
-fi
-
-# Check Snap
-if bundle exec exe/mnenv snap list | grep -q "$VERSION"; then
-  echo "✓ Snap: $VERSION found"
-else
-  echo "✗ Snap: $VERSION not found"
-fi
-
-# Check Homebrew
-if bundle exec exe/mnenv homebrew list | grep -q "$VERSION"; then
-  echo "✓ Homebrew: $VERSION found"
-else
-  echo "✗ Homebrew: $VERSION not found"
-fi
-
-# Check Chocolatey
-if bundle exec exe/mnenv chocolatey list | grep -q "$VERSION"; then
-  echo "✓ Chocolatey: $VERSION found"
-else
-  echo "✗ Chocolatey: $VERSION not found"
-fi
+mnenv versions
 ----
 
-.Get Snap revision for a specific version
+=== Set version
 
 [source,shell]
 ----
-#!/bin/bash
-# get_snap_revision.sh - Get Snap revision for version/arch
+# Set global version (affects all projects)
+mnenv global 1.14.4
 
-VERSION=$1
-ARCH=${2:-amd64}
-CHANNEL=${3:-stable}
+# Set global version with source
+mnenv global 1.14.4 --source binary
 
-if [ -z "$VERSION" ]; then
-  echo "Usage: $0 <version> [arch] [channel]"
-  exit 1
-fi
+# Set local version (affects current directory)
+mnenv local 1.14.4
 
-# Get revision from YAML
-yq ".versions[] | select(.version == \"$VERSION\" and .arch == \"$ARCH\" and .channel == \"$CHANNEL\") | .revision" data/snap/versions.yaml
+# Set shell version (affects current shell session only)
+mnenv use 1.14.4
 ----
 
-.Compare versions across sources
-
-[source,ruby]
-----
-#!/usr/bin/env ruby
-# compare_versions.rb - Compare version availability
-
-require 'json'
-require 'yaml'
-
-SOURCES = %w[gemfile snap homebrew chocolatey].freeze
-
-def load_versions(source)
-  yaml_path = "data/#{source}/versions.yaml"
-  return [] unless File.exist?(yaml_path)
-
-  data = YAML.load_file(yaml_path)
-  data['versions'].map { |v| v['version'] }.uniq
-end
-
-def compare(version)
-  puts "Version #{version} availability:"
-  SOURCES.each do |source|
-    versions = load_versions(source)
-    status = versions.include?(version) ? '✓' : '✗'
-    puts "  #{status} #{source}"
-  end
-end
-
-# Usage: ruby compare_versions.rb 1.14.4
-compare(ARGV[0])
-----
-
-=== Getting Gemfile files for a version
+=== Uninstall a version
 
 [source,shell]
 ----
-# List versions that have Gemfiles extracted
-bundle exec exe/mnenv gemfile list | grep -E "v[0-9]"
-
-# Check if a specific version has Gemfiles
-if [ -f "data/gemfile/v1.14.4/Gemfile" ]; then
-  echo "Gemfile exists for 1.14.4"
-  cat data/gemfile/v1.14.4/Gemfile
-fi
+mnenv uninstall 1.14.4
 
-# Copy Gemfiles to your project
-cp data/gemfile/v1.14.4/Gemfile /path/to/project/
-cp data/gemfile/v1.14.4/Gemfile.lock.archived /path/to/project/Gemfile.lock
+# Force uninstall without confirmation
+mnenv uninstall 1.14.4 --force
 ----
 
-=== Snap-specific queries
-
-Snap versions use composite keys (version-revision-arch-channel). Query them:
+=== Show mnenv version
 
 [source,shell]
 ----
-# List all Snap versions with their revisions
-bundle exec exe/mnenv snap list
-
-# Get all revisions for a specific version
-bundle exec exe/mnenv snap list | grep "1.14.4"
-
-# Get AMD64 stable revision for a version
-yq '.versions[] | select(.version == "1.14.4" and .arch == "amd64" and .channel == "stable") | .revision' data/snap/versions.yaml
-
-# Get all architectures for a version
-yq '.versions[] | select(.version == "1.14.4") | .arch' data/snap/versions.yaml | sort -u
-
-# Get all channels for a version
-yq '.versions[] | select(.version == "1.14.4") | .channel' data/snap/versions.yaml | sort -u
+mnenv version
 ----
 
-=== JSON output for automation
+=== Update version data
 
 [source,shell]
 ----
-# Get all versions as JSON
-bundle exec exe/mnenv list-all -f json > versions.json
-
-# Query JSON with jq
-jq '.gemfile.latest' versions.json
-jq '.snap.versions[] | select(.version == "1.14.4")' versions.json
-jq '.homebrew.count' versions.json
-
-# Use in scripts
-LATEST=$(bundle exec exe/mnenv list-all -f json | jq -r '.gemfile.latest')
-echo "Latest Gemfile version: $LATEST"
+# Update version data from metanorma/versions repository
+mnenv update
 ----
 
-== Data structure
+== Version Sources
 
-Version data is stored in YAML files under `data/`:
+mnenv supports two installation sources:
 
-----
-data/
-├── gemfile/
-│   ├── versions.yaml          # Gemfile version metadata
-│   └── v1.14.4/               # Gemfile extraction per version
-│       ├── Gemfile
-│       └── Gemfile.lock.archived
-├── snap/
-│   └── versions.yaml          # Snap versions with revision data
-├── homebrew/
-│   └── versions.yaml          # Homebrew versions from tags
-└── chocolatey/
-    └── versions.yaml          # Chocolatey versions
-----
-
-=== Version object structure
+[width="100%",cols="25%,75%"]
+|===
+| Source | Description
 
-Each version object contains:
+| `gemfile`
+| RubyGems installation using Gemfile.
+Requires development tools (Ruby, bundler).
+Faster startup with lazy loading.
 
-[source,ruby]
-----
-{
-  "version": "1.14.4",
-  "published_at": "2025-01-15T10:30:00Z",
-  "parsed_at": "2025-01-15T10:30:00Z"
-}
-----
+| `binary`
+| Pre-compiled binaries from
+https://github.com/metanorma/packed-mn[packed-mn] releases.
+No development tools required.
+Full memory load at startup.
+|===
 
-Additional fields per source:
+== Version Resolution
 
-* **Gemfile** - `gemfile_exists`, `gemfile_path`, `gemfile_lock_path`
-* **Snap** - `revision`, `arch`, `channel`
-* **Homebrew** - `tag_name`, `commit_sha`
-* **Chocolatey** - `package_name`, `is_pre_release`
+mnenv resolves the active version in the following order:
 
-=== Using lock files with Bundler
+. `METANORMA_VERSION` environment variable
+. `.metanorma-version` file in current directory (and parent directories)
+. `~/.mnenv/version` file (global version)
 
-To install the exact gems from a specific Metanorma Docker version:
+The source is resolved similarly:
 
-[source,sh]
-----
-# Clone this repository
-git clone https://github.com/metanorma/versions.git
-cd versions
+. `METANORMA_SOURCE` environment variable
+. `.metanorma-source` file in current directory (and parent directories)
+. `~/.mnenv/source` file (global source)
+. Default: `gemfile`
 
-# Copy the files for your desired version
-cp data/gemfile/v1.14.4/Gemfile /path/to/your/project/
-cp data/gemfile/v1.14.4/Gemfile.lock.archived /path/to/your/project/Gemfile.lock
+== Directory Structure
 
-# Install the exact gems
-cd /path/to/your/project
-bundle install
+[source]
 ----
-
-=== Finding the Docker image version
-
-To find which version of metanorma/metanorma Docker image corresponds to a
-metanorma-cli version:
-
-[source,sh]
+~/.mnenv/
+├── versions/           # Version data (cloned from metanorma/versions)
+│   └── data/
+│       ├── gemfile/versions.yaml
+│       ├── binary/versions.yaml
+│       └── ...
+├── installed/          # Installed Metanorma versions
+│   └── 1.14.4/
+│       ├── bin/metanorma    # (gemfile source)
+│       ├── metanorma        # (binary source)
+│       └── source           # Records installation source
+├── shims/              # Shim executables
+│   └── metanorma
+├── version             # Global version file
+└── source              # Global source file
 ----
-# Inspect the Gemfile to see the metanorma-cli version
-cat data/gemfile/v1.14.4/Gemfile
 
-# Output: gem "metanorma-cli", "= 1.14.4"
-----
-
-The Docker image tag is the same as the metanorma-cli version:
+== Architecture
 
-[source,sh]
-----
-docker pull metanorma/metanorma:1.14.4
+mnenv follows a model-driven architecture:
+
+[source]
+----
+mnenv
+├── Cli                    # Thor CLI entry point
+├── Commands/
+│   ├── InstallCommand     # Install versions
+│   ├── VersionCommand     # Version switching (global, local, use, versions)
+│   └── UninstallCommand   # Uninstall versions
+├── Installers/
+│   ├── Base               # Abstract installer
+│   ├── BinaryInstaller    # Binary installation (downloads, extracts)
+│   └── GemfileInstaller   # Gemfile-based installation
+├── Shells/
+│   ├── Base               # Abstract shell
+│   ├── Bash               # Unix shells (bash, zsh, sh)
+│   ├── PowerShell         # Windows PowerShell
+│   └── Cmd                # Windows CMD
+├── Repositories/
+│   ├── GemfileRepository  # RubyGems version data
+│   ├── BinaryRepository   # Binary version data
+│   └── ...
+├── ShimManager            # Shim generation
+├── VersionsManager        # Version data management
+└── Models/
+    ├── ArtifactVersion    # Base version model
+    ├── GemfileVersion     # RubyGems version
+    └── BinaryVersion      # Binary version
 ----
 
 == Development
@@ -530,18 +273,14 @@ docker pull metanorma/metanorma:1.14.4
 
 [source,shell]
 ----
-bundle exec rake test
+bundle exec rake spec
 ----
 
-=== Running Rake tasks
+Or with RSpec directly:
 
 [source,shell]
 ----
-# List available Rake tasks
-bundle exec rake -T
-
-# Generate index
-bundle exec rake generate_index
+bundle exec rspec
 ----
 
 === Code quality
@@ -552,53 +291,21 @@ bundle exec rake generate_index
 bundle exec rubocop
 
 # Auto-correct issues
-bundle exec rubocop --autocorrect
-----
-
-== Architecture
-
-This repository follows a model-driven OOP architecture using lutaml-model:
-
-----
-Mnenv
-├── ArtifactVersion  (base version class with LutaML serialization)
-├── Repository       (YAML CRUD operations)
-├── Fetcher          (API communication)
-├── Logger           (logging utility)
-├── JsonFormatter    (JSON output)
-└── Cli              (Thor CLI with subcommands)
-
-Modules by platform:
-├── Gemfile/
-│   ├── Version      (Gemfile-specific with gemfile paths)
-│   ├── Repository   (Gemfile YAML storage)
-│   ├── Fetcher      (Docker Hub API)
-│   └── Extractor    (Gemfile extraction from containers)
-├── Snap/
-│   ├── Version      (Snap-specific with revision/arch)
-│   ├── Repository   (Snap YAML storage)
-│   └── Fetcher      (Snapcraft API)
-├── Homebrew/
-│   ├── Version      (Homebrew-specific with tag/commit)
-│   ├── Repository   (Homebrew YAML storage)
-│   └── Fetcher      (GitHub tags API)
-└── Chocolatey/
-    ├── Version      (Chocolatey-specific with pre-release flag)
-    ├── Repository   (Chocolatey YAML storage)
-    └── Fetcher      (Chocolatey API)
+bundle exec rubocop -A
 ----
 
 == Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b my-amazing-feature`)
-3. Commit your changes (`git commit -am 'Add some amazing feature'`)
-4. Push to the branch (`git push origin my-amazing-feature`)
-5. Open a Pull Request
+. Fork the repository
+. Create your feature branch (`git checkout -b my-amazing-feature`)
+. Commit your changes (`git commit -am 'Add some amazing feature'`)
+. Push to the branch (`git push origin my-amazing-feature`)
+. Open a Pull Request
 
 == License
 
-This repository is available as open source under the terms of the {file-license}[MIT License].
+This project is available as open source under the terms of the
+https://opensource.org/licenses/MIT[MIT License].
 
 == Copyright