aoc_cli 0.2.3 → 1.0.0

data/README.md

@@ -1,71 +1,39 @@
-# `Advent of Code - cli`
+# `aoc-cli`
 
-![](https://github.com/apexatoll/aoc-files/blob/master/demo2.gif)
+A command-line interface for Advent of Code, built in Ruby.
+
+> [!IMPORTANT]
+> `aoc_cli` has gone through a complete rewrite as of `1.0.0` in order to improve resilience and the overall user interface.
+> The core application has been swapped out to use the [Kangaru](https://github.com/apexatoll/kangaru) command line framework, with a completely new API and removal of bloated features.
+> There are also some other improvements on performance, and removal of some hefty dependencies such as `pandoc`.
+> These are breaking changes, so please pin your version to `0.2.3` if you wish to continue using the previous version.
 
-A command-line interface to interact with Advent of Code puzzles, built in Ruby.
 
 ## Main Features
+
 - Download puzzles as markdown and raw inputs directly from the command line
 - Submit answers for puzzles and receive feedback
-- Track progress through your calendar file which is automatically updated as you progress
-- View data about how you answer puzzles, for example your previous attempts, how long it takes to solve a puzzle successfully and how many attempts it took you
-- Inputs and puzzles are cached locally to prevent strain on AoC server
-- Automatic git initialisation
-- Hot keys to open solution megathreads in Reddit if you get stuck
-- Support for multiple AoC accounts by use of session-key aliases
-
-### Note to Existing Users
-- If you are having any issues with the calendar table, run `aoc -r` in your year directory to update and refresh your directory
-
-## Whats New
-
-### New to 0.2.2
-- Year refresh now creates the calendar table if it does not exist
-- Update terminal-table version requirements
-- Add version flag
-
-### New to 0.2.1 
-- Day subdir prefix functionality
-- Duplicate incorrect attempts prevented
-
-### New to 0.2.0
-- Calendar progress tables
-- Quick-print calendar from any directory
-- Configuration expansion
-	- Auto-generate config file
-	- Turn on/off creation of calendar file
-	- Turn on/off leaderboard stats in calendar file
-	- Basic git integration
-- Better key validation
-- Better default alias handling
-- General bug fixes
+- Track data on your progress through the event
 
 
 ## Installation
 
-- aoc-cli uses Pandoc, make sure it is [installed](https://pandoc.org/installing.html)
-- Homebrew users can run `brew install pandoc`
-- Mac OS users need to make sure developer tools is installed (thank you yspreen)
-
-Install gem
+- As of `1.0.0`, `aoc_cli` no longer requires `pandoc`
+- Other system requirements are `curl` and `sqlite3` and `ruby` >= `3.2.0`
 
-```bash
-$ gem install aoc_cli
-```
 
-Manual install
+Install `aoc_cli` with the following command
 
 ```bash
-$ git clone "https://github.com/apexatoll/aoc-cli"
-$ cd aoc-cli
-$ rake build install
+gem install aoc_cli
 ```
 
+
 ## Setup
 
-### Finding your Session Key
+### Setting your Session Key
 
-To use aoc-cli you must first find and store your unique session cookie. To find this, log into the Advent of Code website as usual and load any page. 
+To use `aoc-cli` you must first find and store your unique session cookie. To find this, log into the Advent of Code website as usual and load any page. 
 
 Open developer tools and open the network tab. Refresh the page and you should see a file that contains your session cookie.
 
@@ -75,314 +43,152 @@ It will contain a field that looks something like:
 cookie: session=HEXADECIMAL_STRING
 ```
 
-This is unique to your account, and allows aoc-cli to interact with the AoC server - do not share this!
+This is unique to your account, and allows `aoc-cli` to interact with the AoC server on your behalf - do not share this or check this into version control.
 
+Your session token should be copied into your configuration file (`~/.config/aoc_cli/config.yml`) under the `session.token` nested key:
 
-### Storing your Session Key
-
-- Copy the session key (including "session=") to the clipboard and open your terminal
-- Run the following command
-
-```bash
-aoc -k $your_key
-
+```yaml
+session:
+  token: <YOUR TOKEN>
 ```
 
-- aoc-cli stores this key under the alias 'main' if no custom alias is specified
-- To store the key under a different alias use the `-u` or `--user` flags followed by the desired alias.
-- Session keys are stored in the aoc config file located at `~/.config/aoc-cli/aoc.rc`.
+> [!IMPORTANT]
+> Make sure to strip the `session=` prefix from the copied token.
 
-Keys can also be stored manually in your config file using the format:
+> [!NOTE]
+> Multiple users used to be a feature pre the 1.0.0 overhaul. This will be
+> reimplemented and released in an upcoming release if there is need for it.
 
-```
-cookie=>$alias=>$key
-```
-
-For example:
-
-```
-cookie=>account2=>session=123abc
-```
 
-### Default Alias
-
-aoc-cli allows for multiple keys to be stored within the config file. 
-
-To see which alias is currently default run `aoc -U` or `aoc --default`
-
-- You can update the default alias by running 
-
-```bash
-aoc -U $new_default_alias
-```
-
-By default, aoc-cli will determine the default alias in the following order of precedence
-
-- The alias explicitly set by `default=>$alias` in your config file or by using the `-U` command
-- The `main` alias (if it exists)
-- The first key in your config file
-
-### Use Case
+## Usage
 
-Say for example you wanted to learn a new language and decided to try out Advent of Code from scratch to get stuck in. You could set up a new account and grab the session key, which for example is `abc123`
+`aoc-cli` is designed to run in a file-tree generated by the application. 
 
-Lets use Ruby as our new language. You could then store this new key under the alias `ruby`
+There are two types of directories
 
-```bash
-aoc -k session=abc123 -u ruby
-```
+1. Event directories
+- These contain puzzle subdirectories
 
-You could then set `ruby` as your default alias so that you do not have to specify `-u ruby` explicitly when initialising a year directory each time
+2. Puzzle subdirectories
+- These contain puzzles, input and your soution code
 
-```bash
-aoc -U ruby
-```
-Alternatively you could add the following line to your config file
+### Directory Structure Example
 
 ```
-default=>ruby
+  2023 <--- Event Directory
+  │     
+  ├── 1 <-- Puzzle Directory
+  │   │ 
+  │   ├── day_1.md
+  │   ├── input
+  │   └── solution.rb
+  └── 2
+      ├── day_2.md
+      ├── input
+      └── solution.rs
 ```
 
-## Usage
-
-aoc-cli is designed to run in a file-tree generated by the interface. 
-
-There are two types of directories
-1. Year directories
-	- These contain your calendar and all day subdirectories
-2. Day subdirectories
-	- These contain the puzzles, your input and your code
-
-## Initialising the Year
+### Initialising an Event
 
-To begin using the cli you must first initialise the year directory. 
+To begin using the cli you must first initialise an event directory. An event directory is the parent directory in which your puzzle directories (and your code solutions) exist.
 
-aoc-cli will intialise within your current working directory, so first create a directory for the year and change directory into it
+> [!NOTE]
+> If you are planning on tackling multiple Advent of Code events, it is probably wise to create a root for your event directories, eg `~/aoc`.
 
-```bash
-mkdir 2020
-cd 2020
-```
-Initialise the year directory using the command 
+To initialize an event, run the following command:
 
 ```bash
-aoc -y 2020
+aoc event init <YEAR>
 ```
 
-This will set the session key for the year directory to the default alias. To use a different alias run:
-
-```bash
-aoc -y 2020 -u $alias
-```
+This will:
 
-This command will create necessary metafiles, download the year calendar and fill it with your current progress (if any). This is stored in a markdown file in the year directory.
+- Fetch your latest stats and setup your progress
+- Create an event directory
 
-By default, your stats in the leaderboard are also added to this file. This can be changed - see Configuration
+At the time of writing, the valid years are 2015 - 2023.
 
-aoc-cli can also intialise a git directory on year intialisation (turned off by default)
 
-## Initialising a Day
+### Initialising a Puzzle
 
-You can now get day data! 
+> [!CAUTION]
+> Please do not check puzzle or input files into your version control system, as this is against Advent of Code rules.
 
-To fetch puzzle instructions and inputs you can run the following command from within the year directory
+Run the following command from an event directory to fetch and initialize a puzzle directory and associated files:
 
 ```bash
-aoc -d $day_number
+aoc puzzle init <DAY>
 ```
 
 This command performs the following actions
 
-- Creates a day subdirectory
-- Fetches the puzzle as markdown
-- Fetches raw puzzle input
-- The time you downloaded the puzzle is logged
+- Creates a puzzle subdirectory
+- Fetches the puzzle as markdown and writes to the puzzle dir
+- Fetches raw puzzle input and writes to the puzzle dir
 
-All puzzles and inputs are cached in aoc-cli on a per-user basis. This means that if you have previously initialised this day under the same alias before, your puzzle and input will be transferred from the cache locally rather than downloading from the aoc server.
+This directory is a good place to write your solution code adjacent to your input and puzzle files.
 
-NB: if you wish to add a prefix to your day subdirectory names, you can add `day_dir_prefix=>$prefix` to your config file
 
-## Solving Puzzles
+### Solving Puzzles
 
-From the day subdirectory you can attempt to solve puzzles by running the command 
+From the puzzle subdirectory you can solve puzzles by running the command 
 
 ```bash
-aoc -s $answer
+aoc puzzle solve --answer <ANSWER>
 ```
 
-You will then receive one of four responses
+You will then receive one of three responses
 
-1. The answer is correct
-2. The answer is not correct
-3. You have already tried this incorrect answer
-4. You have time to wait before submitting an answer
+1. The answer was correct
+2. The answer was not correct
+3. You have time to wait before submitting an answer
 
-If your answer is correct, aoc-cli will automatically update the puzzle instructions and your calendar file. Additionally aoc-cli will calculate how long and how many attempts it took to solve the puzzle (see the Tables section)
+If your answer is correct, `aoc-cli` will automatically update the puzzle instructions and your event progress. 
 
-Incorrect attempts will be logged along with any hint as to whether your answer was too high or too low. 
+Incorrect attempts will be logged along with any hint as to whether your answer was too high or too low. You can recall these using the `puzzle attempts` command.
 
-Trying to answer with the same incorrect answer for the second time will throw an error
-
-If you have sent multiple incorrect attempts AoC will ask you to wait before trying again - be patient!
+If you have sent multiple incorrect attempts AoC will ask you to wait before trying to answer the puzzle again.
 
 
 ## Tables
 
-aoc-cli uses a local database to store information about your progress with puzzles. This tracks data on:
+`aoc-cli` uses a local SQLite database to store information about your progress with puzzles. This tracks data on:
 
-1. Your attempts
-2. Your stats
-3. Your progress in the year
+1. Your progress for the current event
+1. Your attempts for the current puzzle
 
 This data can be visualised in terminal-friendly tables
 
-### Attempts
-
-Previous attempts for a puzzle can be viewed from the day directory by the use of the command
-
-```bash
-aoc -a (--attempts)
-```
-
-To specify which attempts to show from outside the day subdirectory you can use the command
-
-```bash
-aoc -a -u $user_alias -Y $year -D $day -p $part
-```
-
-Data is shown in a formatted table with incorrect attempts shown in red and the correct answer in green.
-
-![](https://github.com/apexatoll/aoc-files/blob/master/attempts.png)
-
-You need to specify the part explicitly using `-p` or `--part` to view attempts for puzzles that are already completed 
 
-### Stats
-
-aoc-cli also tracks data related to your performance in puzzles, namely:
-- The time taken to complete a puzzle
-- How many attempts it took
+### Attempts
 
-To view stats on a specific puzzle run the following command from the day subdirectory
+Previous attempts for a puzzle can be viewed from the puzzle directory by the use of the command:
 
 ```bash
-aoc -S (--stats)
+aoc puzzle attempts
 ```
 
-To view the stats for the year as a whole run the same command from the year directory. 
-
-Flags can be also be added manually for showing data for other users, years and days in a similar way to that of the attempts table
-
-![](https://github.com/apexatoll/aoc-files/blob/master/stats.png)
-
 ### Progress
 
-To view your progress in the year you can run the commands
+To view your progress in the year you can run the following command from within an event or a puzzle directory.
 
 ```bash
-aoc -c (--simple-cal)
+aoc event progress
 ```
 
 This will print a simple table showing your stars for each day. This is created on year initialisation and updated as you complete puzzles
 
-If you have calendar_file set to true in your configuration (default setting), you can quickly print your calendar file by using the command 
-
-```bash
-aoc -C (--fancy-cal)
-```
-
-![calendars](https://github.com/apexatoll/aoc-files/blob/master/calendars.gif)
-
-## Reddit Integration
-
-![reddit](https://github.com/apexatoll/aoc-files/blob/master/reddit.gif)
-
-You can run the command `aoc -R (--reddit)` from the day subdirectory, or by manual flags to open the solution megathread for the specified day in Reddit
-
-If one is installed, aoc-cli will default to opening the thread within a
-reddit-cli such as [rtv](https://github.com/michael-lazar/rtv) or [ttrv](https://github.com/tildeclub/ttrv). 
-
-If one isn't found however, the thread will be opened within your default browser.
-
-To open the reddit megathread in your browser, regardless of whether you have a CLI installed, run `aoc -B (--browser)`
-
-## Git Integration
-
-aoc-cli currently supports basic integration with git. At present aoc-cli can:
-- Initialise a git directory on year initialisation
-- Create a gitignore file
-	- Configurable to add markdown and metafiles by default
 
-These settings can be configured in your config file (see configuration)
+## Help
 
-## Vim Integration
+`aoc-cli` also has built in documentation. You can view this from the terminal using either `aoc help <COMMAND>` or `aoc <COMMAND> --help`.
 
-If you use vim you may wish to set a keybinding to automatically run your code and submit it for validation once you have solved a puzzle.
 
-Using Ruby as an example, you could add the following line to your .vimrc:
+## Contributing
 
-```vim
-autocmd filetype ruby nmap <silent><leader>ac :! aoc -s $(ruby %)<CR>
-```
-
-Executing leader + ac would then run your program and send the answer to the server for verification (as long as your program only outputs an answer and no other text). 
- 
-## Configuration
-
-aoc-cli can be configured using the config file at `~/.config/aoc-cli/aoc.rc`
-
-To generate an example configuration file you can run `aoc -G` or `aoc --gen-config`. (Note this will throw an error if `~/.config/aoc-cli/aoc.rc` already exists)
-
-There is also an example aoc.rc file in the `sample` directory of this repo
+Please create an issue if there are any bugs or problems using `aoc-cli`. Contributions and questions are always welcome.
 
-Settings are added to the aoc-cli config file in the format
-
-```
-setting_name=>setting
-```
-
-Lines can be commented out of the rc file by prefixing with `//`
-
-### List of Configurable Options
-
-| Flag              | Type   | Description                                                   | Default |
-|-------------------|--------|---------------------------------------------------------------|---------|
-| calendar_file     | bool   | Write calendar as a markdown file                             | true    |
-| day_dir_prefix    | string | Add prefix to day subdirectory nam                            | nil     |
-| default           | string | Default alias                                                 | main    |
-| ignore_md_files   | bool   | Auto add md files (calendar and puzzles) to gitignore         | true    |
-| ignore_meta_files | bool   | Auto add meta files to gitignore                              | true    |
-| init_git          | bool   | Initialise a git repository on year initialisation            | false   |
-| lb_in_calendar    | bool   | Include leaderboard stats in calendar file                    | true    |
-| reddit_in_browser | bool   | Always open reddit links in browser                           | false   |
-| unicode_tables    | bool   | Display tables in unicode format. Otherwise ascii format used | true    |
-
-
-## All Flags
-
-| Flag Short | Flag Long      | Action                                               |
-|------------|----------------|------------------------------------------------------|
-| `-a`       | `--attempts`   | Print attempts table                                 |
-| `-B`       | `--browser`    | View reddit megathread in your browser               |
-| `-c`       | `--simple-cal` | Print simplified calendar progress                   |
-| `-C`       | `--fancy-cal`  | Print styled calendar (requires calendar_file=>true) |
-| `-d`       | `--init-day`   | Initialise day subdirectory                          |
-| `-D`       | `--day`        | Manual day specification for aoc command             |
-| `-G`       | `--gen-config` | Write example config file                            |
-| `-h`       | `--help`       | Show help screen                                     |
-| `-k`       | `--key`        | Store session key                                    |
-| `-p`       | `--part`       | Manual part specification for aoc command            |
-| `-r`       | `--refresh`    | Refresh calendar (year dir)                          |
-|            |                | Refresh puzzle (day subdir)                          |
-| `-R`       | `--reddit`     | Open solution megathread                             |
-| `-s`       | `--solve`      | Solve puzzle                                         |
-| `-S`       | `--stats`      | Print stats table                                    |
-| `-u`       | `--user`       | Specify alias for aoc command                        |
-| `-U`       | `--default`    | View default alias, list all aliases (no argument)   |
-| `-y`       | `--init-year`  | Initialise year directory                            |
-| `-Y`       | `--year`       | Specify year for aoc command                         |
 
 ## Acknowledgments
 
-I am in no way affiliated with AoC, but I would like to take this opportunity to thank the creator Eric Wastl for the taking the time and great effort to produce these fantastic puzzles!
-
-Please let me know if there are any bugs or issues with the cli within the issues section - I will try to address them as quickly as I can
+`aoc-cli` is in no way affiliated with Advent of Code, but I would like to take this opportunity to thank the creator, Eric Wastl, for his efforts in producing these fantastic puzzles year on year.

data/Rakefile

@@ -1,3 +1,10 @@
-# frozen_string_literal: true
 require "bundler/gem_tasks"
-task default: %i[]
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,13 @@
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  configure_code_diagnostics do |hash|
+    hash[Steep::Diagnostic::Ruby::FallbackAny] = nil
+    hash[Steep::Diagnostic::Ruby::UnreachableBranch] = nil
+    hash[Steep::Diagnostic::Ruby::UnknownConstant] = :error
+    hash[Steep::Diagnostic::Ruby::MethodDefinitionMissing] = nil
+    hash[Steep::Diagnostic::Ruby::UnsupportedSyntax] = :hint
+  end
+end

data/aoc_cli.gemspec

@@ -1,30 +1,40 @@
 require_relative "lib/aoc_cli/version"
 
 Gem::Specification.new do |spec|
-	spec.name    = "aoc_cli"
-	spec.version = AocCli::VERSION
-	spec.authors = ["Christian Welham"]
-	spec.email   = ["welhamm@gmail.com"]
-	spec.summary = "A command-line interface for the Advent of Code puzzles"
-	spec.description = "A command-line interface for the Advent of Code puzzles. Features include downloading puzzles and inputs, solving puzzles and tracking year progress from within the terminal"
-	spec.homepage = "https://github.com/apexatoll/aoc-cli"
-	spec.license = "MIT"
-	spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
-	spec.metadata["homepage_uri"] = spec.homepage
-	spec.metadata["source_code_uri"] = "https://github.com/apexatoll/aoc-cli"
-	spec.metadata["changelog_uri"] = "https://github.com/apexatoll/aoc-cli/CHANGELOG.md"
-	spec.files = Dir.chdir(File.expand_path(__dir__)) do
-		`git ls-files -z`
-			.split("\x0")
-			.reject{|f| f.match(%r{\A(?:test|spec|features)/}) }
-	end
-	spec.bindir = "bin"
-	spec.executables << 'aoc'
-	spec.require_paths = ["lib"]
-	spec.add_dependency("colorize")
-	spec.add_dependency("curb")
-	spec.add_dependency("git")
-	spec.add_dependency("pandoc-ruby")
-	spec.add_dependency("sqlite3")
-	spec.add_dependency("terminal-table", "~> 3.0.0")
+  spec.name    = "aoc_cli"
+  spec.version = AocCli::VERSION
+  spec.authors = ["Christian Welham"]
+  spec.email   = ["welhamm@gmail.com"]
+
+  spec.summary = "A command-line interface for the Advent of Code puzzles"
+
+  spec.description = <<~DESCRIPTION
+    A command-line interface for the Advent of Code puzzles. Features include \
+    downloading puzzles and inputs, solving puzzles and tracking year progress \
+    from within the terminal
+  DESCRIPTION
+
+  spec.homepage = "https://github.com/apexatoll/aoc-cli"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/apexatoll/aoc-cli"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f == __FILE__ || f.match?(/\A(bin|spec|\.git)/)
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = ["aoc"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "http"
+  spec.add_dependency "kangaru"
+  spec.add_dependency "nokogiri"
+  spec.add_dependency "reverse_markdown"
+  spec.add_dependency "sequel_polymorphic"
+  spec.add_dependency "terminal-table"
 end

data/db/migrate/1_create_events.rb

@@ -0,0 +1,14 @@
+Sequel.migration do
+  change do
+    create_table :events do
+      primary_key :id
+
+      integer :year, null: false
+
+      datetime :created_at
+      datetime :updated_at
+
+      index :year
+    end
+  end
+end

data/db/migrate/2_create_puzzles.rb

@@ -0,0 +1,21 @@
+Sequel.migration do
+  change do
+    create_table :puzzles do
+      primary_key :id
+
+      foreign_key :event_id, :events, null: false
+
+      integer :day, null: false
+
+      text :content, null: false
+      text :input, null: false
+
+      datetime :created_at
+      datetime :updated_at
+      datetime :part_one_completed_at
+      datetime :part_two_completed_at
+
+      index :event_id
+    end
+  end
+end

data/db/migrate/3_create_stats.rb

@@ -0,0 +1,19 @@
+Sequel.migration do
+  change do
+    create_table :stats do
+      primary_key :id
+
+      foreign_key :event_id, :events, null: false
+
+      1.upto(25) do |i|
+        integer :"day_#{i}", null: false, default: 0
+      end
+
+      datetime :created_at
+      datetime :updated_at
+      datetime :completed_at
+
+      index :event_id
+    end
+  end
+end

data/db/migrate/4_create_attempts.rb

@@ -0,0 +1,19 @@
+Sequel.migration do
+  change do
+    create_table :attempts do
+      primary_key :id
+
+      foreign_key :puzzle_id, :puzzles, null: false
+
+      integer :level, null: false
+      text :answer, null: false
+
+      integer :status, null: false
+      integer :hint
+      integer :wait_time
+
+      datetime :created_at
+      datetime :updated_at
+    end
+  end
+end

data/db/migrate/5_create_locations.rb

@@ -0,0 +1,17 @@
+Sequel.migration do
+  change do
+    create_table :locations do
+      primary_key :id
+
+      string :path, null: false
+
+      integer :resource_id, null: false
+      string :resource_type, null: false
+
+      datetime :created_at
+      datetime :updated_at
+
+      index %i[path resource_id resource_type]
+    end
+  end
+end