csvops 0.1.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8621d11595ca64afe19513bbeb253a9568ef78566aff8eec116a2b169e899fce
+  data.tar.gz: '009a655572331c7699ca8c6034d9bcf45db517e90da4ae4317d3b42c6b4aa7dd'
+SHA512:
+  metadata.gz: 542f540de68616558cfe40e39fecbb4a3b91fa7a2bf8fd59397e5a9aad855503795e928c1ddae18c3577e6e3558b34166e3c240e6b7744e11d0c6b8a11297aa6
+  data.tar.gz: 04a5beb85795c5b10984a8a12980a1079a8a4f07f447d6621d6e6961ded35ee18edb5834e5e8fbad99b0f7fd0c76c2aae31f7d2ccc48f3b54a520d7bcbf91931

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+ruby "3.3.0"
+
+gemspec
+
+gem "minitest"
+gem "rake"

data/README.md

@@ -0,0 +1,209 @@
+# CSV Ops CLI
+
+`csvops` is a small Ruby CLI for interactive CSV workflows.
+
+## Requirements
+
+- Ruby 3.3.0
+- Bundler
+- `rake`
+- `minitest`
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### 1. Start the CLI
+
+```bash
+csvtool menu
+```
+
+With Bundler:
+
+```bash
+bundle exec csvtool menu
+```
+
+### 2. Choose an action
+
+```text
+CSV Tool Menu
+1. Extract column
+2. Exit
+>
+```
+
+Select `1` to run extraction.
+
+### 3. Follow prompts
+
+Prompt flow:
+
+- CSV file path
+- Separator (`comma`, `tab`, `semicolon`, `pipe`, or `custom`)
+- Optional header filter + column selection
+- Skip blanks (`Y/n`, default `Y`)
+- Preview + confirmation
+- Output destination (`console` or `file`)
+
+### 4. Example interaction (console output)
+
+Legend: ` ` = prompt/menu, `+` = user input, `-` = tool output
+
+```diff
+ CSV file path: /path/to/file.csv
+ Choose separator:
+ 1. comma (,)
+ 2. tab (\t)
+ 3. semicolon (;)
+ 4. pipe (|)
+ 5. custom
++Separator choice [1]: 1
+ Filter columns (optional):
+ Select column:
+ 1. name
+ 2. city
++Column number: 1
+ Skip blank values? [Y/n]:
+ Preview (first 3 values):
+-Alice
+-Bob
+-Cara
+ Print all values? [y/N]:
++y
+ Output destination:
+ 1. console
+ 2. file
++Output destination [1]: 1
+-Alice
+-Bob
+-Cara
+```
+
+### 5. Example interaction (file output)
+
+```diff
+ Output destination:
+ 1. console
+ 2. file
++Output destination [1]: 2
++Output file path: /tmp/names.csv
+-Wrote output to /tmp/names.csv
+```
+
+### 6. Direct command mode
+
+Extract a column without using the interactive menu:
+
+```bash
+csvtool column /path/to/file.csv column_name
+```
+
+With Bundler:
+
+```bash
+bundle exec csvtool column /path/to/file.csv column_name
+```
+
+## Testing
+
+Run tests:
+
+```bash
+rake test
+```
+
+Or:
+
+```bash
+bundle exec rake test
+```
+
+## Alpha release
+
+Current prerelease version: `0.1.0.alpha`
+
+Install prerelease from RubyGems:
+
+```bash
+gem install csvops --pre
+```
+
+Release runbook:
+
+- `/Users/roberthall/Projects/csvops/docs/release-v0.1.0-alpha.md`
+
+## Architecture
+
+The codebase follows a DDD-lite layered structure:
+
+- `domain/`: core domain model and invariants (`ExtractionSession` aggregate + value objects/entities).
+- `application/`: use-case orchestration (`RunExtraction`).
+- `infrastructure/`: CSV reading/streaming and output adapters (console/file).
+- `interface/cli/`: menu, prompts, and user-facing error presentation.
+- `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
+
+## Domain model
+
+Bounded context: `Column Extraction`.
+
+Core DDD structure:
+
+- Aggregate root: `ExtractionSession`
+  - Controls extraction state transitions (`start`, `with_preview`, `confirm!`, `with_output_destination`).
+  - Enforces session-level invariants.
+- Entities:
+  - `CsvSource` (file path + `Separator`)
+  - `ColumnSelection` (chosen header)
+- Value objects:
+  - `Separator`
+  - `ExtractionOptions` (`skip_blanks`, `preview_limit`)
+  - `Preview` (list of `ExtractionValue`)
+  - `ExtractionValue`
+  - `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunExtraction` orchestrates one extraction request.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::ValueStreamer`
+  - `Infrastructure::Output::ConsoleWriter`
+  - `Infrastructure::Output::CsvFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+flowchart LR
+  UI["Interface CLI\n(Menu + Prompts + Errors)"] --> APP["Application Use Case\nRunExtraction"]
+  APP --> AGG["Domain Aggregate\nExtractionSession"]
+
+  AGG --> E1["Entity\nCsvSource"]
+  AGG --> E2["Entity\nColumnSelection"]
+  AGG --> V1["Value Objects\nSeparator / ExtractionOptions / Preview / OutputDestination / ExtractionValue"]
+
+  APP --> INFCSV["Infrastructure CSV\nHeaderReader + ValueStreamer"]
+  APP --> INFOUT["Infrastructure Output\nConsoleWriter + CsvFileWriter"]
+```
+
+## Project layout
+
+```text
+bin/tool              # CLI entrypoint
+lib/csvtool/cli.rb
+lib/csvtool/domain/extraction_session/*
+lib/csvtool/application/use_cases/run_extraction.rb
+lib/csvtool/infrastructure/csv/*
+lib/csvtool/infrastructure/output/*
+lib/csvtool/interface/cli/menu_loop.rb
+lib/csvtool/interface/cli/prompts/*
+lib/csvtool/interface/cli/errors/presenter.rb
+test/csvtool/cli_test.rb         # end-to-end workflow tests
+test/csvtool/**/*_test.rb        # focused unit tests by component folder
+test/test_helper.rb
+```

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/bin/csvtool

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "csvtool/cli"
+
+exit Csvtool::CLI.start(ARGV, stdin: $stdin, stdout: $stdout, stderr: $stderr)

data/bin/tool

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "csvtool/cli"
+
+exit Csvtool::CLI.start(ARGV, stdin: $stdin, stdout: $stdout, stderr: $stderr)

data/csvops.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/csvtool/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "csvops"
+  spec.version = Csvtool::VERSION
+  spec.authors = ["Robert Hall"]
+  spec.email = [""]
+
+  spec.summary = "Interactive CSV column extraction CLI"
+  spec.description = "A small Ruby CLI for extracting CSV columns interactively or via direct command."
+  spec.homepage = "https://github.com/RobertAndrewHall/csvops"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.files = Dir.glob("{lib,exe,bin,test,docs}/**/*") + %w[README.md Gemfile Rakefile csvops.gemspec]
+  spec.bindir = "exe"
+  spec.executables = ["csvtool"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "csv", "~> 3.3"
+  spec.add_development_dependency "minitest", "~> 6.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

data/docs/release-v0.1.0-alpha.md

@@ -0,0 +1,73 @@
+# Release Checklist: v0.1.0-alpha
+
+## 1. Verify environment
+
+```bash
+ruby -v
+bundle -v
+```
+
+Expected:
+- Ruby `3.3.0`
+
+## 2. Install dependencies
+
+```bash
+bundle install
+```
+
+## 3. Run quality checks
+
+```bash
+bundle exec rake test
+```
+
+## 4. Smoke test CLI commands
+
+```bash
+printf '2\n' | bundle exec csvtool menu
+bundle exec csvtool column test/fixtures/sample_people.csv name
+```
+
+Expected output for `column` command:
+
+```text
+Alice
+Bob
+Cara
+```
+
+## 5. Build and validate gem package
+
+```bash
+gem build csvops.gemspec
+gem install ./csvops-0.1.0.alpha.gem
+csvtool column test/fixtures/sample_people.csv name
+```
+
+## 6. Commit release prep
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v0.1.0-alpha"
+```
+
+## 7. Tag release
+
+```bash
+git tag -a v0.1.0-alpha -m "v0.1.0-alpha"
+git push origin main --tags
+```
+
+## 8. Publish gem (optional for alpha)
+
+```bash
+gem push csvops-0.1.0.alpha.gem
+```
+
+## 9. Create GitHub release
+
+Create release `v0.1.0-alpha` with:
+- Summary of supported commands (`menu`, `column`)
+- Known limitations
+- Install instructions (`gem install csvops --pre`)

data/exe/csvtool

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "csvtool/cli"
+
+exit Csvtool::CLI.start(ARGV, stdin: $stdin, stdout: $stdout, stderr: $stderr)

data/lib/csvtool/application/use_cases/run_extraction.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "csv"
+require "csvtool/interface/cli/errors/presenter"
+require "csvtool/interface/cli/prompts/file_path_prompt"
+require "csvtool/interface/cli/prompts/separator_prompt"
+require "csvtool/interface/cli/prompts/column_selector_prompt"
+require "csvtool/interface/cli/prompts/skip_blanks_prompt"
+require "csvtool/interface/cli/prompts/confirm_prompt"
+require "csvtool/interface/cli/prompts/output_destination_prompt"
+require "csvtool/infrastructure/csv/header_reader"
+require "csvtool/infrastructure/csv/value_streamer"
+require "csvtool/services/preview_builder"
+require "csvtool/infrastructure/output/console_writer"
+require "csvtool/infrastructure/output/csv_file_writer"
+require "csvtool/domain/extraction_session/separator"
+require "csvtool/domain/extraction_session/csv_source"
+require "csvtool/domain/extraction_session/column_selection"
+require "csvtool/domain/extraction_session/extraction_options"
+require "csvtool/domain/extraction_session/extraction_value"
+require "csvtool/domain/extraction_session/preview"
+require "csvtool/domain/extraction_session/output_destination"
+require "csvtool/domain/extraction_session/extraction_session"
+
+module Csvtool
+  module Application
+    module UseCases
+      class RunExtraction
+        def initialize(stdin:, stdout:)
+          @stdin = stdin
+          @stdout = stdout
+          @errors = Interface::CLI::Errors::Presenter.new(stdout: stdout)
+          @header_reader = Infrastructure::CSV::HeaderReader.new
+          @value_streamer = Infrastructure::CSV::ValueStreamer.new
+          @preview_builder = Services::PreviewBuilder.new(value_streamer: @value_streamer)
+        end
+
+        def call
+          file_path = Interface::CLI::Prompts::FilePathPrompt.new(stdin: @stdin, stdout: @stdout).call
+          return @errors.file_not_found(file_path) unless File.file?(file_path)
+
+          col_sep = Interface::CLI::Prompts::SeparatorPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call
+          return if col_sep.nil?
+          separator = Domain::ExtractionSession::Separator.new(col_sep)
+
+          source = Domain::ExtractionSession::CsvSource.new(path: file_path, separator: separator)
+          headers = @header_reader.call(file_path: source.path, col_sep: source.separator.value)
+          return @errors.no_headers if headers.empty?
+
+          column_name = Interface::CLI::Prompts::ColumnSelectorPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call(headers)
+          return if column_name.nil?
+          column_selection = Domain::ExtractionSession::ColumnSelection.new(name: column_name)
+
+          skip_blanks = Interface::CLI::Prompts::SkipBlanksPrompt.new(stdin: @stdin, stdout: @stdout).call
+          options = Domain::ExtractionSession::ExtractionOptions.new(skip_blanks: skip_blanks, preview_limit: 10)
+          session = Domain::ExtractionSession::ExtractionSession.start(
+            source: source,
+            column_selection: column_selection,
+            options: options
+          )
+
+          preview_values = @preview_builder.call(
+            file_path: session.source.path,
+            column_name: session.column_selection.name,
+            col_sep: session.source.separator.value,
+            skip_blanks: session.options.skip_blanks?,
+            limit: session.options.preview_limit
+          )
+          preview = Domain::ExtractionSession::Preview.new(
+            values: preview_values.map { |value| Domain::ExtractionSession::ExtractionValue.new(value) }
+          )
+          session = session.with_preview(preview)
+
+          confirmed = Interface::CLI::Prompts::ConfirmPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call(session.preview.to_strings)
+          return unless confirmed
+          session = session.confirm!
+
+          output_destination = Interface::CLI::Prompts::OutputDestinationPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call
+          return if output_destination.nil?
+          domain_destination =
+            if output_destination[:mode] == :file
+              Domain::ExtractionSession::OutputDestination.file(path: output_destination[:path])
+            else
+              Domain::ExtractionSession::OutputDestination.console
+            end
+          session = session.with_output_destination(domain_destination)
+
+          write_output(
+            session.output_destination,
+            file_path: session.source.path,
+            column_name: session.column_selection.name,
+            col_sep: session.source.separator.value,
+            skip_blanks: session.options.skip_blanks?
+          )
+        rescue CSV::MalformedCSVError
+          @errors.could_not_parse_csv
+        rescue Errno::EACCES
+          @errors.cannot_read_file(file_path)
+        end
+
+        private
+
+        def writer_for(output_destination)
+          if output_destination.file?
+            Infrastructure::Output::CsvFileWriter.new(stdout: @stdout, errors: @errors, value_streamer: @value_streamer)
+          else
+            Infrastructure::Output::ConsoleWriter.new(stdout: @stdout, value_streamer: @value_streamer)
+          end
+        end
+
+        def write_output(output_destination, file_path:, column_name:, col_sep:, skip_blanks:)
+          writer = writer_for(output_destination)
+          args = {
+            file_path: file_path,
+            column_name: column_name,
+            col_sep: col_sep,
+            skip_blanks: skip_blanks
+          }
+          args[:output_path] = output_destination.path if output_destination.file?
+          writer.call(**args)
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/cli.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "csv"
+require "csvtool/interface/cli/menu_loop"
+require "csvtool/application/use_cases/run_extraction"
+require "csvtool/interface/cli/errors/presenter"
+require "csvtool/infrastructure/csv/header_reader"
+require "csvtool/infrastructure/csv/value_streamer"
+require "csvtool/infrastructure/output/console_writer"
+
+module Csvtool
+  class CLI
+    MENU_OPTIONS = [
+      "Extract column",
+      "Exit"
+    ].freeze
+
+    def self.start(argv, stdin:, stdout:, stderr:)
+      new(argv, stdin: stdin, stdout: stdout, stderr: stderr).run
+    end
+
+    def initialize(argv, stdin:, stdout:, stderr:)
+      @argv = argv
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run
+      case @argv.first
+      when "menu"
+        run_menu_loop
+      when "column"
+        run_column_command
+      else
+        print_usage
+        1
+      end
+    end
+
+    private
+
+    def run_menu_loop
+      extract_action = -> { Application::UseCases::RunExtraction.new(stdin: @stdin, stdout: @stdout).call }
+      Interface::CLI::MenuLoop.new(
+        stdin: @stdin,
+        stdout: @stdout,
+        menu_options: MENU_OPTIONS,
+        extract_action: extract_action
+      ).run
+    end
+
+    def print_usage
+      @stderr.puts "Usage:"
+      @stderr.puts "  csvtool menu"
+      @stderr.puts "  csvtool column <file> <column>"
+    end
+
+    def run_column_command
+      file_path = @argv[1]
+      column_name = @argv[2]
+      unless file_path && column_name
+        print_usage
+        return 1
+      end
+
+      errors = Interface::CLI::Errors::Presenter.new(stdout: @stdout)
+      return errors.file_not_found(file_path) || 1 unless File.file?(file_path)
+
+      header_reader = Infrastructure::CSV::HeaderReader.new
+      headers = header_reader.call(file_path: file_path, col_sep: ",")
+      return errors.no_headers || 1 if headers.empty?
+      return errors.column_not_found || 1 unless headers.include?(column_name)
+
+      value_streamer = Infrastructure::CSV::ValueStreamer.new
+      writer = Infrastructure::Output::ConsoleWriter.new(stdout: @stdout, value_streamer: value_streamer)
+      writer.call(file_path: file_path, column_name: column_name, col_sep: ",", skip_blanks: true)
+      0
+    rescue CSV::MalformedCSVError
+      errors.could_not_parse_csv
+      1
+    rescue Errno::EACCES
+      errors.cannot_read_file(file_path)
+      1
+    end
+  end
+end

data/lib/csvtool/domain/extraction_session/column_selection.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module ExtractionSession
+      class ColumnSelection
+        attr_reader :name
+
+        def initialize(name:)
+          raise ArgumentError, "column name cannot be empty" if name.to_s.empty?
+
+          @name = name
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/domain/extraction_session/csv_source.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module ExtractionSession
+      class CsvSource
+        attr_reader :path, :separator
+
+        def initialize(path:, separator:)
+          raise ArgumentError, "path cannot be empty" if path.to_s.empty?
+
+          @path = path
+          @separator = separator
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/domain/extraction_session/extraction_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module ExtractionSession
+      class ExtractionOptions
+        attr_reader :skip_blanks, :preview_limit
+
+        def initialize(skip_blanks:, preview_limit:)
+          raise ArgumentError, "preview_limit must be positive" unless preview_limit.to_i.positive?
+
+          @skip_blanks = !!skip_blanks
+          @preview_limit = preview_limit
+        end
+
+        def skip_blanks?
+          @skip_blanks
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/domain/extraction_session/extraction_session.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module ExtractionSession
+      class ExtractionSession
+        attr_reader :source, :column_selection, :options, :preview, :output_destination
+
+        def self.start(source:, column_selection:, options:)
+          new(source: source, column_selection: column_selection, options: options)
+        end
+
+        def initialize(source:, column_selection:, options:, preview: nil, output_destination: nil, confirmed: false)
+          @source = source
+          @column_selection = column_selection
+          @options = options
+          @preview = preview
+          @output_destination = output_destination
+          @confirmed = confirmed
+        end
+
+        def with_preview(preview)
+          self.class.new(
+            source: @source,
+            column_selection: @column_selection,
+            options: @options,
+            preview: preview,
+            output_destination: @output_destination,
+            confirmed: @confirmed
+          )
+        end
+
+        def confirm!
+          self.class.new(
+            source: @source,
+            column_selection: @column_selection,
+            options: @options,
+            preview: @preview,
+            output_destination: @output_destination,
+            confirmed: true
+          )
+        end
+
+        def with_output_destination(destination)
+          self.class.new(
+            source: @source,
+            column_selection: @column_selection,
+            options: @options,
+            preview: @preview,
+            output_destination: destination,
+            confirmed: @confirmed
+          )
+        end
+
+        def confirmed?
+          @confirmed
+        end
+      end
+    end
+  end
+end