fasti 1.0.0

data/README.md

@@ -0,0 +1,416 @@
+# :spiral_calendar: Fasti
+
+[![Gem Version](https://badge.fury.io/rb/fasti.svg)](https://badge.fury.io/rb/fasti)
+[![CI](https://github.com/sakuro/fasti/workflows/CI/badge.svg)](https://github.com/sakuro/fasti/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Gem Downloads](https://img.shields.io/gem/dt/fasti.svg)](https://rubygems.org/gems/fasti)
+[![Depfu](https://badges.depfu.com/badges/57045bfa6f47bc651aa055b9bd4e5387/overview.svg)](https://depfu.com/github/sakuro/fasti)
+
+A flexible calendar application with multi-country holiday support, written in Ruby. Fasti provides beautiful, colorful calendar displays with support for multiple output formats, configurable week start days, and country-specific holiday highlighting.
+
+## Features
+
+- **Multiple Display Formats**: Month, quarter (3 months), and full year views
+- **Configurable Week Start**: Start weeks on any day of the week
+- **Holiday Support**: Country-specific holiday highlighting using the holidays gem
+- **Historical Calendar Transitions**: Julian to Gregorian calendar transitions with country-specific gap handling
+- **Color Coding**: ANSI color support for holidays, weekends, and today's date
+- **Configuration File**: XDG-compliant Ruby-based configuration file support (`~/.config/fasti/config.rb`)
+- **Locale Detection**: Automatic country detection from `LC_ALL` and `LANG` environment variables
+- **Command Line Interface**: Full-featured CLI with comprehensive options
+
+## Installation
+
+Install the gem by executing:
+
+```bash
+gem install fasti
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem 'fasti'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Usage
+
+Display the current month:
+```bash
+fasti
+```
+
+Display a specific month and year:
+```bash
+fasti 6 2024
+```
+
+### Display Formats
+
+**Month View** (default):
+```bash
+fasti 6 2024 --format month
+# Or using shortcuts:
+fasti 6 2024 --month
+fasti 6 2024 -m
+```
+
+**Quarter View** (3 months side by side):
+```bash
+fasti 6 2024 --format quarter
+# Or using shortcuts:
+fasti 6 2024 --quarter
+fasti 6 2024 -q
+```
+
+**Year View** (all 12 months):
+```bash
+fasti 2024 --format year
+# Or using shortcuts:
+fasti 2024 --year
+fasti 2024 -y
+```
+
+### Week Start Configuration
+
+You can start the week on any day of the week:
+
+```bash
+fasti --start-of-week sunday     # Default
+fasti --start-of-week monday     # Common international standard
+fasti --start-of-week tuesday
+fasti --start-of-week wednesday
+fasti --start-of-week thursday
+fasti --start-of-week friday
+fasti --start-of-week saturday
+```
+
+### Country and Holiday Support
+
+Specify country for holiday highlighting:
+```bash
+fasti --country JP    # Japan
+fasti --country US    # United States
+fasti --country GB    # United Kingdom
+fasti --country DE    # Germany
+```
+
+Fasti automatically detects your country from environment variables (`LC_ALL`, `LANG`), but you can override this with the `--country` option.
+
+### Historical Calendar Transitions
+
+For historical dates, Fasti supports country-specific Julian to Gregorian calendar transitions with proper gap handling:
+
+```bash
+# Show October 1582 (Italian transition) - compressed display
+fasti 10 1582 --country IT
+
+# British transition - September 3-13, 1752 never existed in Britain
+fasti 9 1752 --country GB
+
+# Asian countries transitioned from lunisolar calendars
+# Japan transitioned in 1873 (Meiji era)
+fasti 12 1872 --country JP
+
+# Korea transitioned in 1896 (Korean Empire era)
+fasti 12 1895 --country KR
+
+# France had different transition date than Italy
+fasti 12 1582 --country FR
+
+# Sweden's complex transition in 1753
+fasti 3 1753 --country SE
+```
+
+Calendar transitions are displayed in compressed format (like UNIX `cal` command) for continuous display without confusing gaps.
+
+Supported countries with calendar transition dates:
+
+**Early Catholic adoption (1582-1583):**
+- Italy, Spain, Portugal (1582-10-15)
+- France (1582-12-20) 
+- Belgium/Spanish Netherlands (1583-01-06)
+
+**Protestant countries (1700-1753):**
+- Netherlands (1700-07-12), Switzerland (1700-01-23), Denmark/Norway (1700-03-01)
+- Great Britain & colonies: US, Canada, Australia, etc. (1752-09-14)
+- Sweden (1753-03-01)
+
+**Eastern Europe (1916-1927):**
+- Bulgaria (1916), Russia (1918), Romania/Yugoslavia (1919), Greece (1923), Turkey (1927)
+
+**Asian countries (1873-1967):**
+- Japan (1873), China/Taiwan (1912), Korea (1896), Vietnam (1967), Thailand (1888)
+
+Note: Asian countries transitioned from lunisolar calendars to Gregorian; pre-transition dates use proleptic Gregorian calendar for computational consistency.
+
+### Command Line Options
+
+```
+Usage: fasti [month] [year] [options]
+
+Arguments:
+  month  Month (1-12, optional)
+  year   Year (optional)
+
+Format options:
+  -f, --format FORMAT           Output format (month, quarter, year)
+  -m, --month                   Display month format (equivalent to --format month)
+  -q, --quarter                 Display quarter format (equivalent to --format quarter)
+  -y, --year                    Display year format (equivalent to --format year)
+
+Calendar display options:
+  -w, --start-of-week WEEKDAY   Week start day (any day of the week)
+  -c, --country COUNTRY         Country code for holidays (e.g., JP, US, GB, DE)
+  -s, --style STYLE             Custom styling (e.g., "sunday:bold holiday:foreground=red today:inverse")
+
+Other options:
+  -v, --version                 Show version
+  -h, --help                    Show this help
+```
+
+### Positional Arguments
+
+**No arguments** - Display current month:
+```bash
+fasti
+```
+
+**One argument** - Interpreted based on value:
+- 1-12: Month for current year
+- 13+: Year for current month
+
+```bash
+fasti 6        # June current year
+fasti 2024     # Current month 2024
+```
+
+**Two arguments** - Month and year:
+```bash
+fasti 6 2024   # June 2024
+```
+
+### Configuration File
+
+Create a configuration file at `~/.config/fasti/config.rb` (or `$XDG_CONFIG_HOME/fasti/config.rb`) using Ruby syntax to set default options:
+
+```ruby
+# Example configuration
+Fasti.configure do |config|
+  config.format = :quarter
+  config.start_of_week = :monday
+  config.country = :US
+  # Custom styling (optional)
+  config.style = {
+    sunday: { bold: true },
+    holiday: { foreground: :red, bold: true },
+    today: { inverse: true }
+  }
+end
+```
+
+See `examples/config.rb` for a complete configuration example.
+
+Command line options override configuration file settings.
+
+### Styling
+
+By default, Fasti displays all days with normal text styling. You can customize the appearance of different day types using the `style` configuration option:
+
+- **sunday**: Configurable styling for Sundays
+- **holiday**: Configurable styling for holidays  
+- **today**: Configurable styling for today's date
+- **monday, tuesday, etc.**: Configurable styling for individual weekdays
+
+You can apply styling using the `--style` option with space-separated target:attribute pairs:
+
+```bash
+# Bold Sundays and red holidays
+fasti --style "sunday:bold holiday:foreground=red"
+
+# Multiple attributes for the same target
+fasti --style "today:bold,inverse sunday:foreground=blue"
+
+# Mix different styling attributes
+fasti --style "sunday:bold holiday:foreground=red,background=yellow today:inverse"
+
+# Override config file settings with no- prefix (boolean attributes only)
+fasti --style "sunday:no-bold,no-italic holiday:foreground=red"  # Remove boolean styling
+```
+
+### Examples
+
+Display current month with Monday start:
+```bash
+fasti --start-of-week monday
+```
+
+Display current month with Wednesday start:
+```bash
+fasti --start-of-week wednesday
+```
+
+Show quarter view for summer 2024 in Japan:
+```bash
+fasti 7 2024 --format quarter --country JP
+```
+
+Full year 2024 with US holidays:
+```bash
+fasti 2024 --format year --country US
+```
+
+## Environment Variables
+
+Fasti respects the following environment variables for automatic country detection:
+
+- `LC_ALL` (highest priority)
+- `LANG` (fallback)
+
+Note: Only `LC_ALL` and `LANG` are used for country detection. Other `LC_*` variables (such as `LC_MESSAGES`, `LC_TIME`) are not used as they represent specific locale categories rather than the user's preferred country for holiday context.
+
+Example:
+```bash
+export LANG=ja_JP.UTF-8  # Automatically uses Japan (JP) holidays
+fasti
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies:
+
+```bash
+git clone https://github.com/sakuro/fasti.git
+cd fasti
+bin/setup
+```
+
+Run the tests (includes coverage measurement):
+```bash
+bundle exec rake spec
+```
+
+Run linting:
+```bash
+bundle exec rake rubocop
+```
+
+Generate API documentation:
+```bash
+bundle exec rake doc
+```
+
+Clean temporary files:
+```bash
+bundle exec rake clean
+```
+
+Remove all generated files:
+```bash
+bundle exec rake clobber
+```
+
+Run all checks:
+```bash
+bundle exec rake
+```
+
+To install this gem onto your local machine:
+```bash
+bundle exec rake install
+```
+
+For an interactive prompt that allows you to experiment:
+```bash
+bin/console
+```
+
+## Dependencies
+
+- **dry-configurable** (~> 1.0): Configuration management
+- **dry-schema** (~> 1.13): Configuration validation
+- **dry-types** (~> 1.7): Type system for configuration
+- **holidays** (~> 8.0): Country-specific holiday data
+- **locale** (~> 2.1): Locale parsing for country detection
+- **tint_me** (~> 1.0): ANSI color support
+- **zeitwerk** (~> 2.6): Code autoloading
+
+## Development Dependencies
+
+- **rspec** (~> 3.0): Testing framework
+- **rubocop** (~> 1.21): Code linting
+- **simplecov** (~> 0.22): Code coverage measurement
+- **yard** (from GitHub): API documentation generation with Data class support
+
+## Releasing
+
+This project uses automated GitHub Actions workflows for releases. Maintainers can create new releases with a simple workflow execution.
+
+### Quick Release Process
+
+1. Go to **Actions** → **Release Preparation** → **Run workflow**
+2. Enter version number (e.g., `1.0.0`)
+3. Review and merge the generated PR
+4. Release is automatically published to RubyGems and GitHub
+
+**For detailed instructions, troubleshooting, and setup requirements, see [`.github/RELEASING.md`](.github/RELEASING.md).**
+
+## Known Limitations
+
+### Historical Calendar Support
+
+Fasti properly handles historical calendar transitions with country-specific transition dates. Each country switched from Julian to Gregorian calendar at different times, and these transition periods contain non-existent dates that are handled correctly.
+
+Historical transition periods display correctly with proper gap handling:
+
+```bash
+# Italian transition works correctly - shows compressed display
+fasti 10 1582 --country IT
+
+# Asian countries show transitions from lunisolar calendars
+fasti 12 1872 --country JP
+```
+
+**Note**: Standard UNIX calendar tools like `cal` and `gcal` correctly handle these historical transitions by appropriately skipping non-existent dates during calendar reforms.
+
+**Technical Details**: Fasti uses country-specific Julian to Gregorian calendar transition dates with proper gap handling. Ruby's `Date` class uses Italy's transition date (`Date::ITALY`) by default, but Fasti's `CalendarTransition` class supports transitions for different countries, properly handling non-existent dates during calendar reforms.
+
+**Available Countries**: Fasti supports **25+ countries** with calendar transitions:
+- **Catholic countries**: Italy/Spain/Portugal (1582), France (1582), Belgium (1583)
+- **Protestant countries**: Netherlands (1700), Switzerland (1700), Denmark/Norway (1700), Great Britain & colonies (1752), Sweden (1753)  
+- **Eastern Europe**: Bulgaria (1916), Russia (1918), Romania/Yugoslavia (1919), Greece (1923), Turkey (1927)
+- **Asian countries**: Japan (1873), China/Taiwan (1912), Korea (1896), Vietnam (1967), Thailand (1888)
+
+Asian countries used lunisolar calendars before adoption; pre-transition dates use proleptic Gregorian calendar for computational consistency.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sakuro/fasti.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`bundle exec rake spec`)
+5. Ensure code passes linting (`bundle exec rake rubocop`)
+6. Commit your changes (`git commit -am 'Add some feature'`)
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+- Built with Ruby 3.2+ for broad compatibility and modern features
+- Uses the excellent [holidays](https://github.com/holidays/holidays) gem for accurate holiday data
+- Color support provided by the [tint_me](https://github.com/ddfreyne/tint-me) gem
+- Follows XDG Base Directory Specification for configuration files

data/RELEASING.md

@@ -0,0 +1,202 @@
+# Releasing
+
+This document describes the release process for Ruby gems used in this project, which is fully automated through GitHub Actions workflows.
+
+## Overview
+
+The release process consists of three automated workflows:
+
+1. **Release Preparation** - Creates a release branch with version updates
+2. **Release Validation** - Validates the release branch on PR creation
+3. **Release Publish** - Publishes the gem after PR merge
+
+## Prerequisites
+
+Before initiating a release, ensure:
+
+- [ ] All desired features and fixes are merged to `main`
+- [ ] CI is passing on `main` branch
+- [ ] `CHANGELOG.md` has entries under `## [Unreleased]` section
+- [ ] `RUBYGEMS_API_KEY` secret is configured in repository settings
+
+## Release Process
+
+### Step 1: Initiate Release
+
+1. Go to the [Actions tab](../../actions) in the GitHub repository
+2. Select "Release Preparation" workflow
+3. Click "Run workflow"
+4. Enter the version number (e.g., `1.0.0`)
+5. Click "Run workflow"
+
+The workflow will automatically:
+- Create a new branch `release-v{version}`
+- Update `lib/[gem_name]/version.rb` with the new version
+- Update `CHANGELOG.md`:
+  - Replace `## [Unreleased]` with `## [{version}] - {date}`
+  - Add a new `## [Unreleased]` section for future changes
+- Create a git tag `v{version}` on the release branch
+- Push the branch and tag to GitHub
+- Create a Pull Request to `main`
+
+### Step 2: Review and Merge
+
+Once the PR is created, the Release Validation workflow automatically:
+- Validates version format (must be `x.y.z`)
+- Verifies version consistency between branch name and `version.rb`
+- Checks that the git tag doesn't already exist (or can be updated)
+- Confirms the version isn't already published on RubyGems
+- Verifies `RUBYGEMS_API_KEY` secret is configured
+- Validates `CHANGELOG.md` has an entry for this version
+
+**Note**: Quality checks (tests and RuboCop) are handled by the CI workflow to avoid duplication.
+
+**Important**: If you push additional commits to the release PR (e.g., bug fixes, workflow updates, documentation changes):
+- The validation workflow automatically moves the release tag to the latest commit
+- This ensures the tag always points to the final reviewed code
+- No manual intervention required
+- All changes will be included in the final release
+
+If all checks pass, merge the PR.
+
+### Step 3: Automatic Publishing
+
+After the PR is merged, the Release Publish workflow automatically:
+- Checks out the exact git tag created on the release branch
+- Builds the gem from the tagged commit
+- Publishes the gem to RubyGems
+- Creates a GitHub Release with:
+  - Release notes extracted from `CHANGELOG.md`
+  - The built gem file as an attachment
+- Cleans up the release branch
+
+## Workflow Architecture
+
+### Key Design Decisions
+
+#### Tag-Based Deployment
+
+The release workflow uses a **tag-based deployment strategy** to ensure the released gem contains exactly the code that was reviewed and approved in the release PR, without any subsequent changes from `main`.
+
+```mermaid
+graph LR
+    A[main branch] -->|Create release branch| B[release-v1.0.0]
+    B -->|Update version & tag| C[Tagged: v1.0.0]
+    B -->|Create PR| D[Pull Request]
+    A -->|Other PRs merged| E[main with new commits]
+    D -->|Merge PR| E
+    C -->|Checkout tag| F[Build & Publish gem]
+    F -->|Contains only| G[Code from release branch]
+```
+
+#### Automatic Tag Movement
+
+When additional commits are pushed to a release PR, the tag automatically moves to the latest commit:
+
+```mermaid
+graph LR
+    A[Initial commit] -->|Tag v1.0.0| B[Tagged commit]
+    B -->|Fix typo| C[New commit]
+    C -->|Auto-move tag| D[Tag v1.0.0 on latest]
+    D -->|Final review| E[Ready to merge]
+```
+
+This ensures:
+- The tag always points to the final reviewed code
+- No manual tag management required
+- The published gem matches exactly what was approved
+
+## Manual Release (Emergency Only)
+
+If automation fails, you can release manually using our tag-based strategy:
+
+```bash
+# 1. Create release branch
+git checkout -b release-v1.0.0
+
+# 2. Update version
+vim lib/[gem_name]/version.rb
+
+# 3. Update CHANGELOG (move content from [Unreleased] to [1.0.0])
+vim CHANGELOG.md
+
+# 4. Commit changes and create tag
+git add -A
+git commit -m ":bookmark: Release v1.0.0"
+git tag -a v1.0.0 -m "Release v1.0.0"
+
+# 5. Push release branch and tag
+git push origin release-v1.0.0
+git push origin v1.0.0
+
+# 6. Create PR and merge after review
+gh pr create --title "Release v1.0.0" --body "Release v1.0.0"
+# (Review and merge PR)
+
+# 7. Checkout the tag and build gem
+git checkout v1.0.0
+bundle exec rake build
+
+# 8. Push to RubyGems
+gem push pkg/[gem_name]-1.0.0.gem
+
+# 9. Create GitHub release
+gh release create v1.0.0 --title "[gem_name] v1.0.0" --generate-notes pkg/[gem_name]-1.0.0.gem
+```
+
+## Troubleshooting
+
+### Release Validation Fails
+
+**Version already exists on RubyGems**
+- Solution: Increment the version number and try again
+
+**RUBYGEMS_API_KEY not configured**
+1. Generate an API key at https://rubygems.org/profile/edit
+2. Go to repository Settings → Secrets and variables → Actions
+3. Add new secret: `RUBYGEMS_API_KEY` with your API key
+
+**Tests or RuboCop failing**
+- These are checked by the CI workflow, not in release validation
+- Fix the issues on the release branch or `main` as appropriate
+- Release validation focuses on version consistency and format
+
+### Release Publish Fails
+
+**Tag not found**
+- The release preparation workflow may have failed to create the tag
+- Check if the tag exists: `git tag | grep v1.0.0`
+- If missing, the release validation workflow will recreate it on PR updates
+- For manual fix: create tag on release branch with `git tag -a v1.0.0 -m "Release v1.0.0"`
+
+**Gem push fails**
+- Verify RubyGems API key is valid
+- Check if you have push permissions for the gem
+- Ensure the version doesn't already exist on RubyGems
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible functionality additions  
+- **PATCH** version for backwards-compatible bug fixes
+
+Examples:
+- `0.1.0` → `0.1.1`: Bug fixes only
+- `0.1.1` → `0.2.0`: New features added
+- `0.2.0` → `1.0.0`: Breaking changes or stable release
+
+## Workflow Files
+
+The release automation is implemented in:
+
+- `.github/workflows/release-preparation.yml` - Creates release branch and PR
+- `.github/workflows/release-validation.yml` - Validates release PR
+- `.github/workflows/release-publish.yml` - Publishes gem after merge
+
+## Security Notes
+
+- The `RUBYGEMS_API_KEY` secret is only accessible to workflows running on the default branch
+- Release branches are automatically deleted after successful release
+- All releases are tagged for audit trail and rollback capability

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rake/clean"
+CLEAN.include("coverage", ".rspec_status", ".yardoc")
+CLOBBER.include("docs/api", "pkg")
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "gemoji"
+require "yard"
+YARD::Rake::YardocTask.new(:doc)
+Rake::Task[:doc].enhance do
+  # Convert GitHub emoji shortcodes to actual emojis in generated HTML
+  Dir["docs/api/**/*.html"].each do |file|
+    content = File.read(file)
+
+    # Replace :emoji_name: patterns with actual unicode emojis
+    content.gsub!(/:([a-z0-9+\-_]+):/) do |match|
+      alias_name = $1
+      emoji = Emoji.find_by_alias(alias_name)
+      emoji ? emoji.raw : match # Keep original if emoji not found
+    end
+
+    File.write(file, content)
+  end
+end
+
+task default: %i[spec rubocop]

data/TODO.md

@@ -0,0 +1,11 @@
+# TODO
+
+**Tasks were previously managed in this file, but have been migrated to GitHub Issues for better tracking and collaboration.**
+
+## Quick Links
+- [Open Issues](https://github.com/sakuro/fasti/issues)
+- [Current Milestone](https://github.com/sakuro/fasti/milestones)
+- [All Milestones](https://github.com/sakuro/fasti/milestones?state=closed)
+- [Project Board](https://github.com/sakuro/fasti/projects) (planned)
+
+For ongoing maintenance guidelines, see the [AI Development Guide](CLAUDE.md).