codeball 0.2.0

data/lib/codeball/ball.rb

@@ -0,0 +1,54 @@
+module Codeball
+  # A codeball -- the aggregate root.
+  #
+  # Ball starts empty and grows as entries are added, like a snowball.
+  # It does not touch the filesystem. Parse is a thin factory that
+  # wires Cursor -> Stream -> Ball.
+  #
+  class Ball
+    def self.parse(text)
+      raise MalformedBallError, "empty input, nothing to extract" if text.nil? || text.strip.empty?
+
+      ball = new
+      stream = Stream.new(cursor: Cursor.new(text))
+      stream.each_entry { |entry| ball.add_entry(entry) }
+      ball.validate!
+      ball
+    end
+
+    def initialize
+      @entries = []
+      @warnings = []
+    end
+
+    def add_entry(entry)
+      @entries << entry
+      @warnings << entry.error if entry.errors?
+      @warnings << "truncated entry for #{entry.path.inspect} - missing END marker" if entry.truncated?
+    end
+
+    def validate!
+      valid = entries.select(&:valid?)
+      if valid.empty? && warnings.any?
+        raise MalformedBallError, "no valid entries found (#{warnings.length} malformed)"
+      elsif valid.empty?
+        raise MalformedBallError, "no content found - is this a codeball?"
+      end
+    end
+
+    def each_entry(&) = entries.select(&:valid?).each(&)
+    def each_text_entry(&) = entries.select(&:valid?).select(&:text?).each(&)
+    def each_non_text_entry(&) = entries.select(&:valid?).reject(&:text?).each(&)
+    def each_warning(&) = warnings.each(&)
+    def all_text? = entries.select(&:valid?).all?(&:text?)
+    def warning_count = warnings.length
+
+    def serialize
+      entries.select(&:valid?).select(&:text?).map(&:serialize).join
+    end
+
+    private
+
+    attr_reader :entries, :warnings
+  end
+end

data/lib/codeball/body.rb

@@ -0,0 +1,9 @@
+require "delegate"
+
+module Codeball
+  # File content extracted from between markers in a codeball.
+  #
+  # String wrapper providing identity for pattern matching.
+  #
+  class Body < SimpleDelegator; end
+end

data/lib/codeball/border.rb

@@ -0,0 +1,47 @@
+module Codeball
+  # Domain knowledge about the visual delimiter between sections in a codeball.
+  #
+  # Borders are repeated punctuation patterns that separate entries in
+  # serialized codeball text. The pattern is fixed, not configurable.
+  #
+  # During serialization, SEPARATOR is used as-is.
+  # During parsing, recognition is heuristic to tolerate mangling
+  # by browsers, editors, and clipboard transfer.
+  #
+  module Border
+    PATTERN = "---\t"
+    WIDTH = 10
+    SEPARATOR = (PATTERN * WIDTH).freeze
+    SUFFIX = /[-#=~*_|+][-#=~*_|+\s]{8,}\s*\z/
+    MIN_LENGTH = 6
+    MIN_PUNCTUATION_LENGTH = 9
+
+    module_function
+
+    def recognize?(line)
+      return false if line.empty?
+      return false if line.start_with?("BEGIN ", "END ")
+
+      stripped = line.gsub(/\s+/, "")
+      return false if stripped.empty?
+      return false if stripped.length < MIN_LENGTH
+
+      single_char?(stripped) || punctuation_run?(stripped)
+    end
+
+    def strip_suffix(text)
+      text.match?(SUFFIX) ? text.sub(SUFFIX, "").chomp : text
+    end
+
+    def single_char?(stripped)
+      chars = stripped.chars.uniq
+      chars.length == 1 && !chars.first.match?(/[a-zA-Z0-9]/)
+    end
+
+    def punctuation_run?(stripped)
+      stripped.match?(/\A[-#=~*_|+]+\z/) && stripped.length >= MIN_PUNCTUATION_LENGTH
+    end
+
+    private_class_method :single_char?, :punctuation_run?
+  end
+end

data/lib/codeball/cli.rb

@@ -0,0 +1,24 @@
+require "command_kit/commands"
+require "command_kit/commands/auto_load"
+require "command_kit/options/version"
+
+module Codeball
+  # Main CLI entry point for Codeball.
+  #
+  class CLI
+    include CommandKit::Commands
+    include CommandKit::Description
+    include CommandKit::Options::Version
+
+    version Codeball::VERSION
+
+    # Auto-load subcommands from lib/codeball/commands/*.rb
+    include CommandKit::Commands::AutoLoad.new(
+      dir: File.join(__dir__, "commands"),
+      namespace: "Codeball::Commands",
+    )
+
+    command_name "codeball"
+    description "Bidirectional file bundler for clipboard-friendly LLM workflows"
+  end
+end

data/lib/codeball/commands/diff.rb

@@ -0,0 +1,51 @@
+require "command_kit"
+require "command_kit/command"
+require "command_kit/colors"
+
+module Codeball
+  module Commands
+    # Diff extracted files against local copies.
+    #
+    # Incomplete -- diff output is not yet implemented.
+    #
+    class Diff < CommandKit::Command
+      include CommandKit::Colors
+
+      usage "[options] [FILE]"
+      description "Diff codeball entries against local files"
+
+      option :output_dir, short: "-o",
+                          value: { type: String, default: "." },
+                          desc: "Directory to compare against"
+
+      argument :file, required: false,
+                      desc: "Codeball file (or stdin if omitted)"
+
+      examples [
+        "bundle.txt",
+        "< bundle.txt",
+      ]
+
+      def run(file = nil)
+        input = read_input(file)
+        ball = Ball.parse(input)
+
+        ball.each_warning { |msg| stderr.puts colors.yellow("warning: #{msg}") }
+
+        # Diff output not yet implemented
+      end
+
+      private
+
+      def read_input(file)
+        ARGV.replace(file ? [file] : [])
+        input = ARGF.read
+
+        return input unless input.nil? || input.strip.empty?
+
+        print_error "no input"
+        exit 1
+      end
+    end
+  end
+end

data/lib/codeball/commands/list.rb

@@ -0,0 +1,49 @@
+require "command_kit/commands/command"
+require "command_kit/printing/tables"
+require "command_kit/colors"
+require_relative "../../command_kit/printing"
+require_relative "../../command_kit/combined_io"
+
+module Codeball
+  module Commands
+    # List files contained in a codeball.
+    class List < CommandKit::Commands::Command
+      include CommandKit::CombinedIO
+      include CommandKit::Colors
+      include CommandKit::Printing::Tables
+
+      usage "[options] [FILE]"
+      description "List files in a codeball"
+
+      argument :file, required: false, desc: "Codeball file (or stdin if omitted)"
+
+      examples ["bundle.txt", "< bundle.txt"]
+
+      def env
+        (super || {}).merge("TERM" => "1")
+      end
+
+      def run(io)
+        input = io.read
+        abort_if_empty(input)
+
+        ball = Ball.parse(input)
+
+        ball.each_warning { |msg| stderr.puts colors.yellow("warning: #{msg}") }
+
+        rows = []
+        ball.each_entry { |e| rows << [e.path, "#{e.line_count} lines"] }
+        print_table_color(rows, header: %w[File Lines], color: :green, index: 0)
+      end
+
+      private
+
+      def abort_if_empty(input)
+        return unless input.nil? || input.strip.empty?
+
+        print_error "no input"
+        exit 1
+      end
+    end
+  end
+end

data/lib/codeball/commands/pack.rb

@@ -0,0 +1,54 @@
+require "command_kit/commands/command"
+
+module Codeball
+  module Commands
+    # Pack files into a codeball for clipboard transfer.
+    #
+    class Pack < CommandKit::Commands::Command
+      usage "[options] FILE..."
+
+      description "Pack files into a codeball for clipboard transfer"
+
+      option :quiet, short: "-q", long: "--quiet", desc: "Suppress non-error output"
+
+      argument :files, required: true,
+                       repeats: true,
+                       desc: "Files to pack"
+
+      examples [
+        "lib/*.rb",
+        "src/**/*.py",
+        "README.md lib/*.rb",
+      ]
+
+      def run(*files)
+        readable, unreadable = validate_files(files)
+        ball = Ball.new
+        readable.each do |path|
+          entry = Entry.from_file(path)
+          ball.add_entry(entry) if entry
+        end
+
+        warn_skipped(unreadable, ball)
+        puts ball.serialize
+
+        exit 1 if unreadable.any? || !ball.all_text?
+      end
+
+      private
+
+      def validate_files(files)
+        files
+          .map { Pathname(it) }
+          .partition { it.exist? && it.readable? }
+      end
+
+      def warn_skipped(unreadable, ball)
+        return if options[:quiet]
+
+        unreadable.each { print_error "cannot read file: #{it}" }
+        ball.each_non_text_entry { |entry| print_error "skipping non-text file: #{entry.path} (#{entry.mime_type})" }
+      end
+    end
+  end
+end

data/lib/codeball/commands/unpack.rb

@@ -0,0 +1,123 @@
+require "command_kit/commands/command"
+require "command_kit/colors"
+
+module Codeball
+  module Commands
+    # Extract files from a codeball.
+    #
+    class Unpack < CommandKit::Commands::Command
+      include CommandKit::Colors
+
+      usage "[options] [FILE]"
+      description "Extract files from a codeball"
+
+      option :output_dir, short: "-o",
+                          value: { type: String, default: "." },
+                          desc: "Output directory"
+
+      option :dry_run, short: "-n",
+                       desc: "Preview extraction without writing files"
+
+      option :quiet, short: "-q", long: "--quiet", desc: "Suppress non-error output"
+
+      argument :file, required: false,
+                      desc: "Codeball file (or stdin if omitted)"
+
+      examples [
+        "bundle.txt",
+        "-n bundle.txt",
+        "-o extracted/ bundle.txt",
+        "< bundle.txt",
+      ]
+
+      def run(file = nil)
+        ball = Ball.parse(read_input(file))
+        dest = build_destination
+
+        ball.each_warning { |msg| warn colors.yellow("warning: #{msg}") }
+        ball.each_entry { |entry| dest.write(entry) { |outcome| print_outcome(outcome) } }
+
+        print_summary(dest.summary(malformed: ball.warning_count))
+      end
+
+      private
+
+      def build_destination
+        Destination.new(options[:output_dir], dry_run: options[:dry_run])
+      end
+
+      def read_input(file)
+        ARGV.replace(file ? [file] : [])
+        input = ARGF.read
+
+        abort_on_empty(input)
+        input
+      end
+
+      def abort_on_empty(input)
+        return unless input.nil? || input.strip.empty?
+
+        print_error "no input"
+        exit 1
+      end
+
+      def puts(...)
+        return if options[:quiet]
+
+        stdout.puts(...)
+      end
+
+      def warn(...)
+        return if options[:quiet]
+
+        stderr.puts(...)
+      end
+
+      def print_outcome(outcome)
+        case outcome.status
+        when :written then print_written(outcome)
+        when :dry_run then print_dry_run(outcome)
+        when :unsafe  then print_unsafe(outcome)
+        when :failed  then print_failed(outcome)
+        end
+      end
+
+      def print_written(outcome)
+        puts "#{colors.green("wrote")}: #{outcome.path} (#{outcome.line_count} lines)"
+      end
+
+      def print_dry_run(outcome)
+        puts "#{colors.cyan("[dry-run]")} would write: #{outcome.path} (#{outcome.line_count} lines)"
+      end
+
+      def print_unsafe(outcome)
+        warn colors.yellow("warning: skipping unsafe path #{outcome.path.inspect}")
+      end
+
+      def print_failed(outcome)
+        warn colors.red("error: #{outcome.path}: #{outcome.error}")
+      end
+
+      def print_summary(summary)
+        prefix = summary.dry_run? ? "#{colors.cyan("[dry-run]")} " : ""
+        puts "---"
+        puts "#{prefix}#{summary_parts(summary).join(", ")}"
+      end
+
+      def summary_parts(summary)
+        parts = [colors.green("extracted: #{summary.extracted}").to_s]
+        parts << skipped_part(summary)
+        parts << colors.yellow("malformed: #{summary.malformed}") if summary.malformed.positive?
+        parts
+      end
+
+      def skipped_part(summary)
+        if summary.skipped.positive?
+          colors.yellow("skipped: #{summary.skipped}")
+        else
+          "skipped: 0"
+        end
+      end
+    end
+  end
+end

data/lib/codeball/cursor.rb

@@ -0,0 +1,115 @@
+module Codeball
+  # A lexer for codeball-formatted text.
+  #
+  # Cursor walks text line by line and classifies each meaningful
+  # element as a typed token: Header, Body, or Footer. Borders are
+  # delimiters consumed internally -- they are never yielded.
+  #
+  # Cursor does not correlate tokens or enforce sequencing.
+  # Stream handles assembly; Entry enforces invariants.
+  #
+  class Cursor
+    BEGIN_PATTERN = /\ABEGIN\s+["']?(.+?)["']?\s*\z/
+    END_PATTERN = /\AEND\s+["']?(.+?)["']?\s*\z/
+
+    # Sentinel returned when all tokens have been consumed.
+    module EOF; end
+
+    def initialize(text)
+      @lines = text.lines
+      @position = 0
+      @pending_footer = nil
+      @body_lines = nil
+    end
+
+    def next_item
+      return emit_footer if @pending_footer
+
+      skip_borders
+      return EOF if finished?
+
+      if @body_lines
+        read_body
+      else
+        read_header_or_eof
+      end
+    end
+
+    private
+
+    attr_reader :lines, :position
+
+    def finished? = position >= lines.length
+    def current_line = lines[position]&.strip
+    def raw_line = lines[position]
+
+    def advance
+      @position += 1
+    end
+
+    def peek_line
+      lines[position + 1]&.strip
+    end
+
+    def skip_borders
+      advance while !finished? && Border.recognize?(current_line)
+    end
+
+    def read_header_or_eof
+      match = current_line&.match(BEGIN_PATTERN)
+      return EOF unless match
+
+      advance
+      skip_borders
+      @body_lines = []
+      Header.new(match[1])
+    end
+
+    def read_body
+      collect_body_lines
+      body = Body.new(Border.strip_suffix(@body_lines.join))
+      @body_lines = nil
+      body
+    end
+
+    def collect_body_lines
+      until finished?
+        return found_end_after_border if border_before_end?
+        return found_end_inline if inline_end_marker?
+
+        @body_lines << raw_line
+        advance
+      end
+    end
+
+    def border_before_end?
+      Border.recognize?(current_line) &&
+        peek_line&.match?(END_PATTERN)
+    end
+
+    def inline_end_marker?
+      return false unless current_line&.match?(END_PATTERN)
+
+      @body_lines.empty? || @body_lines.last&.match?(Border::SUFFIX)
+    end
+
+    def found_end_inline
+      match = current_line.match(END_PATTERN)
+      @pending_footer = match[1]
+      advance
+    end
+
+    def found_end_after_border
+      advance
+      end_match = current_line.match(END_PATTERN)
+      @pending_footer = end_match[1]
+      advance
+    end
+
+    def emit_footer
+      path = @pending_footer
+      @pending_footer = nil
+      Footer.new(path)
+    end
+  end
+end

data/lib/codeball/destination.rb

@@ -0,0 +1,76 @@
+require "pathname"
+
+module Codeball
+  # A filesystem context that writes entries to an output directory.
+  #
+  # Destination decorates a directory path with the ability to receive
+  # codeball entries. It owns path safety validation, parent directory
+  # creation, and dry-run simulation.
+  #
+  # Tracks outcomes internally and provides a summary when asked.
+  #
+  class Destination
+    DANGEROUS_PATTERNS = [
+      /\A\.\./,
+      %r{/\.\.},
+      %r{\A/},
+      /\A~/,
+    ].freeze
+
+    attr_reader :output_dir
+
+    def initialize(output_dir = ".", dry_run: false)
+      @output_dir = Pathname.new(output_dir).expand_path
+      @dry_run = dry_run ? true : false
+      @results = []
+    end
+
+    def dry_run? = @dry_run
+
+    def write(entry)
+      outcome = write_entry(entry)
+      @results << outcome
+      yield outcome if block_given?
+      outcome
+    end
+
+    def summary(malformed: 0)
+      ExtractionSummary.new(@results, malformed: malformed)
+    end
+
+    private
+
+    def write_entry(entry)
+      return unsafe_result(entry) unless safe_path?(entry.path)
+
+      resolved = resolve(entry.path)
+      dry_run? ? dry_run_result(entry, resolved) : persist(entry, resolved)
+    rescue SystemCallError => e
+      ExtractionResult.new(path: entry.path, error: e.message, status: :failed)
+    end
+
+    def safe_path?(path)
+      return false if DANGEROUS_PATTERNS.any? { |pattern| path.match?(pattern) }
+
+      resolve(path).to_s.start_with?(output_dir.to_s)
+    end
+
+    def resolve(path)
+      (output_dir / path).expand_path
+    end
+
+    def unsafe_result(entry)
+      ExtractionResult.new(path: entry.path, status: :unsafe)
+    end
+
+    def dry_run_result(entry, resolved)
+      ExtractionResult.new(path: resolved, line_count: entry.line_count, status: :dry_run)
+    end
+
+    def persist(entry, resolved)
+      resolved.parent.mkpath
+      resolved.write(entry.contents)
+      ExtractionResult.new(path: resolved, line_count: entry.line_count, status: :written)
+    end
+  end
+end