codeball 0.2.0

data/lib/codeball/entry.rb

@@ -0,0 +1,107 @@
+require "pathname"
+require "filemagic"
+
+module Codeball
+  # A single file within a codeball.
+  #
+  # Entry is a state machine with write-once setters for header, body,
+  # and footer. It enforces the Header -> Body -> Footer sequence by
+  # rejecting duplicate assignments and detecting mismatched footers.
+  #
+  # Two construction paths, same invariants:
+  #   1. Token-by-token via Stream (parsing)
+  #   2. All-at-once via Entry.from_file (packing)
+  #
+  class Entry
+    attr_reader :header, :body, :footer, :error
+
+    def self.from_file(path)
+      pathname = Pathname.new(path)
+      return nil unless pathname.exist? && pathname.readable?
+
+      entry = new
+      name = pathname.to_s
+      entry.header = Header.new(name)
+      entry.body = Body.new(pathname.read)
+      entry.footer = Footer.new(name)
+      entry
+    end
+
+    def self.magic_client
+      @magic_client ||= FileMagic.mime
+    end
+
+    def initialize
+      @header = nil
+      @body = nil
+      @footer = nil
+      @error = nil
+      @magic_client = self.class.magic_client
+    end
+
+    def header=(header)
+      if @header
+        @error = "duplicate header: already have #{@header}, received #{header}"
+        return
+      end
+      @header = header
+    end
+
+    def body=(body)
+      if @body
+        @error = "duplicate body for #{path}"
+        return
+      end
+      @body = body
+    end
+
+    def footer=(footer)
+      if @footer
+        @error = "duplicate footer for #{path}"
+        return
+      end
+      @footer = footer
+      @error = "footer #{footer} does not match header #{header}" unless footer_matches_header?
+    end
+
+    def valid? = !!(header && body && footer && !errors? && footer_matches_header?)
+    def incomplete? = !valid? && !errors?
+    def errors? = !error.nil?
+    def truncated? = !!(header && (body.nil? || footer.nil?) && !errors?)
+
+    def path = header&.to_s
+    def contents = body&.to_s
+
+    def empty? = contents&.empty? || contents.nil?
+    def byte_size = contents&.bytesize || 0
+
+    def line_count
+      return 0 if contents.nil? || contents.empty?
+
+      contents.count("\n") + (contents.end_with?("\n") ? 0 : 1)
+    end
+
+    def text?
+      contents.nil? || contents.empty? || !mime_type.include?("charset=binary")
+    end
+
+    def serialize
+      border = Border::SEPARATOR
+      "#{border}\nBEGIN #{path.inspect}\n#{border}\n#{contents}#{border}\nEND #{path.inspect}\n#{border}\n"
+    end
+
+    def mime_type
+      @mime_type ||= @magic_client.buffer(contents)
+    end
+
+    private
+
+    attr_reader :magic_client
+
+    def footer_matches_header?
+      return true unless header && footer
+
+      header.to_s == footer.to_s
+    end
+  end
+end

data/lib/codeball/error.rb

@@ -0,0 +1,4 @@
+module Codeball
+  # Base error class for all Codeball-specific exceptions.
+  class Error < StandardError; end
+end

data/lib/codeball/extraction_result.rb

@@ -0,0 +1,16 @@
+module Codeball
+  # Represents the outcome of extracting a single entry from a codeball.
+  #
+  # ## Example
+  #
+  # ```ruby
+  #   puts "Wrote #{result.path}"
+  #   puts "Failed: #{result.error}"
+  # ```
+  #
+  ExtractionResult = Struct.new(:path, :line_count, :status, :error) do
+    # Whether the extraction completed successfully.
+    # Both actual writes and dry-run simulations count as success.
+    def success? = %i[written dry_run].include?(status)
+  end
+end

data/lib/codeball/extraction_summary.rb

@@ -0,0 +1,17 @@
+module Codeball
+  # Aggregates results from extracting multiple entries.
+  # Pure data class - no output methods.
+  #
+  class ExtractionSummary
+    attr_reader :results, :malformed
+
+    def initialize(results, malformed: 0)
+      @results = results
+      @malformed = malformed
+    end
+
+    def extracted = results.count(&:success?)
+    def skipped = results.count { !it.success? }
+    def dry_run? = results.any? { it.status == :dry_run }
+  end
+end

data/lib/codeball/footer.rb

@@ -0,0 +1,9 @@
+require "delegate"
+
+module Codeball
+  # A file path extracted from an END marker in a codeball.
+  #
+  # String wrapper providing identity for pattern matching.
+  #
+  class Footer < SimpleDelegator; end
+end

data/lib/codeball/header.rb

@@ -0,0 +1,9 @@
+require "delegate"
+
+module Codeball
+  # A file path extracted from a BEGIN marker in a codeball.
+  #
+  # String wrapper providing identity for pattern matching.
+  #
+  class Header < SimpleDelegator; end
+end

data/lib/codeball/malformed_ball_error.rb

@@ -0,0 +1,3 @@
+module Codeball
+  class MalformedBallError < Error; end
+end

data/lib/codeball/stream.rb

@@ -0,0 +1,60 @@
+module Codeball
+  # Assembles Entry objects from a stream of tokens produced by Cursor.
+  #
+  # Stream pulls tokens one at a time, feeds them to the current Entry,
+  # and emits it when Entry reports valid or errored. Stream does not
+  # know the Header -> Body -> Footer rules -- Entry enforces those
+  # through its write-once setters.
+  #
+  # Nothing is discarded. Every entry -- valid, errored, or truncated
+  # -- is emitted so the consumer can decide what to do with it.
+  #
+  class Stream
+    include Enumerable
+
+    def initialize(cursor:)
+      @cursor = cursor
+      new_entry
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      consume_tokens(&block)
+      emit_incomplete(&block)
+    end
+
+    alias each_entry each
+
+    private
+
+    attr_reader :cursor
+
+    def consume_tokens
+      while (item = cursor.next_item) != Cursor::EOF
+        feed(item)
+
+        if @current_entry.valid? || @current_entry.errors?
+          yield @current_entry
+          new_entry
+        end
+      end
+    end
+
+    def emit_incomplete
+      yield @current_entry if @current_entry&.incomplete? && @current_entry.header
+    end
+
+    def new_entry
+      @current_entry = Entry.new
+    end
+
+    def feed(item)
+      case item
+      in Header => header then @current_entry.header = header
+      in Body => body then @current_entry.body = body
+      in Footer => footer then @current_entry.footer = footer
+      end
+    end
+  end
+end

data/lib/codeball/version.rb

@@ -0,0 +1,3 @@
+module Codeball
+  VERSION = "0.2.0".freeze
+end

data/lib/codeball.rb

@@ -0,0 +1,23 @@
+require "warning"
+require "zeitwerk"
+
+##
+# Bidirectional file packer for clipboard-friendly LLM workflows.
+#
+# Packs multiple source files into a single plaintext codeball and extracts
+# them back to disk. Uses Zeitwerk for autoloading.
+module Codeball
+  LOADER = Zeitwerk::Loader.for_gem
+  LOADER.inflector.inflect("cli" => "CLI")
+  LOADER.ignore("#{__dir__}/command_kit")
+  LOADER.setup
+
+  # CLI requires command_kit gem - only load if available
+  begin
+    require "command_kit"
+    require_relative "codeball/cli"
+    Warning.ignore(/FileMagic/)
+  rescue LoadError
+    # command_kit not installed, CLI unavailable
+  end
+end

data/lib/command_kit/combined_io.rb

@@ -0,0 +1,28 @@
+require "command_kit/open"
+
+module CommandKit
+  # Opens readable arguments as IO streams, defaulting to stdin.
+  # Uses <tt>CommandKit::Open#open</tt> to handle filenames and +"-"+ for stdin.
+  module CombinedIO
+    include CommandKit::Open
+
+    def self.included(base)
+      base.prepend Prepended
+    end
+
+    # Prepends +run+ to open file arguments (or stdin) as IO streams.
+    module Prepended
+      def run(*args)
+        args << "-" if args.empty?
+
+        ios = args.map { |readable| self.open(readable) }
+
+        begin
+          super(*ios)
+        ensure
+          ios.each(&:close)
+        end
+      end
+    end
+  end
+end

data/lib/command_kit/printing.rb

@@ -0,0 +1,42 @@
+module CommandKit
+  # Extends +CommandKit::Printing+ with color-aware table printing.
+  #
+  # Computes column widths from raw text, then applies ANSI color
+  # after padding so escape sequences don't break alignment.
+  module Printing
+    def print_table_color(rows, header: nil, color: :green, index: 0, **)
+      all_rows = header ? [header] + rows : rows
+      widths = column_widths(all_rows)
+      print_header(header, widths) if header
+      rows.each do |row|
+        line = format_row(row, widths, color, index)
+        puts line.join("  ")
+      end
+    end
+
+    private
+
+    def print_header(header, widths)
+      line = header.each_with_index.map do |cell, i|
+        colors.bold(cell.to_s.ljust(widths[i]))
+      end
+      puts line.join("  ")
+    end
+
+    def format_row(row, widths, color, index)
+      row.each_with_index.map do |cell, i|
+        padded = cell.to_s.ljust(widths[i])
+        i == index ? colors.public_send(color, padded) : padded
+      end
+    end
+
+    def column_widths(rows)
+      rows.each_with_object(Hash.new(0)) do |row, widths|
+        row.each_with_index do |cell, i|
+          len = cell.to_s.length
+          widths[i] = len if len > widths[i]
+        end
+      end
+    end
+  end
+end

data/scripts/codeball_xtract

@@ -0,0 +1,42 @@
+#!/usr/bin/env zsh
+
+typeset -A opt_args
+
+zparseopts \
+  -D \
+  -E \
+  -K \
+  -A \
+  opt_args \
+  -F \
+  - \
+  -envelope
+
+(( ? != 0 )) && return 1
+
+filter() {
+  local pattern1=${1:?}
+  {
+    if (( $+opt_args[--envelope] )); then
+	    print -u2 envelope
+      noglob sed -n "/BEGIN ${(qqq)pattern1}/,/END/p"
+    else
+      noglob sed -n "/BEGIN ${(qqq)pattern1}/,/END/{//d;p}"
+    fi
+   } \
+  | sed '1d;$d'
+}
+
+ codeball_xtract () {
+  emulate -L zsh
+  setopt pipefail
+  setopt errreturn
+  setopt warnnestedvar
+  setopt warncreateglobal
+  local matcher=${1:?} 
+  local file=${2:-/dev/stdin}
+  local pattern1="[^\"]*${matcher}[^\"]*"
+  filter $pattern1 < $file
+}
+
+codeball_xtract ${@}

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: codeball
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- David Gillis
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: command_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Pack multiple source files into a single plaintext codeball for pasting
+  into LLM context windows, then unpack the response back into files.
+email:
+- david@flipmine.com
+executables:
+- codeball
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- LICENSE.txt
+- README.md
+- Rakefile
+- data/wont_pack.md
+- exe/codeball
+- issues.rec
+- lib/codeball.rb
+- lib/codeball/ball.rb
+- lib/codeball/body.rb
+- lib/codeball/border.rb
+- lib/codeball/cli.rb
+- lib/codeball/commands/diff.rb
+- lib/codeball/commands/list.rb
+- lib/codeball/commands/pack.rb
+- lib/codeball/commands/unpack.rb
+- lib/codeball/cursor.rb
+- lib/codeball/destination.rb
+- lib/codeball/entry.rb
+- lib/codeball/error.rb
+- lib/codeball/extraction_result.rb
+- lib/codeball/extraction_summary.rb
+- lib/codeball/footer.rb
+- lib/codeball/header.rb
+- lib/codeball/malformed_ball_error.rb
+- lib/codeball/stream.rb
+- lib/codeball/version.rb
+- lib/command_kit/combined_io.rb
+- lib/command_kit/printing.rb
+- scripts/codeball_xtract
+homepage: https://github.com/gillisd/codeball
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Bidirectional file packer for clipboard-friendly LLM workflows
+test_files: []