spawnpoint 0.2.0

data/exe/spwn

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "spawnpoint/cli"
+
+exit Spawnpoint::CLI.run(ARGV)

data/lib/spawnpoint/cli.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module Spawnpoint
+  # CLI implements the spwn command-line interface.
+  #
+  # It is a thin wrapper around Git. It renames Git commands into friendlier,
+  # game-like language and delegates the actual work to Git.
+  #
+  # The mapping from "spwn commands" to Git invocations lives in the
+  # COMMANDS table below so it is easy to extend without changing the
+  # dispatch logic.
+  module CLI
+    extend self
+
+    # ---------------------------------------------------------------------
+    # Helper methods
+    # ---------------------------------------------------------------------
+
+    def git(*args)
+      system("git", *args)
+    end
+
+    def say(message)
+      puts message
+    end
+
+    def error(message)
+      say("Oops: #{message}")
+    end
+
+    def ask_yes_no(question)
+      loop do
+        print "#{question} (y/n): "
+        answer = STDIN.gets.to_s.strip.downcase
+        return true if answer == "y"
+        return false if answer == "n"
+        say("Please type y or n.")
+      end
+    end
+
+    def extract_message_from_args(args)
+      message_parts = []
+      remaining = []
+      i = 0
+      while i < args.length
+        if args[i] == "-m" && i + 1 < args.length
+          message_parts << args[i + 1]
+          i += 2
+        elsif args[i] == "--message" && i + 1 < args.length
+          message_parts << args[i + 1]
+          i += 2
+        else
+          remaining << args[i]
+          i += 1
+        end
+      end
+      [message_parts.join(" "), remaining]
+    end
+
+    def files_from_args(args, allow_all: false)
+      if allow_all && args.include?("-A")
+        ["-A"]
+      elsif args.empty? || args.include?(".")
+        ["."]
+      else
+        args
+      end
+    end
+
+    def command_args_include_help?(args)
+      args.include?("--help") || args.include?("-h")
+    end
+
+    def git_command_exists?(name)
+      # A quick probe using git's own error reporting.
+      system("git", name, "--help", out: File::NULL, err: File::NULL)
+    end
+
+    def file_on_head?(path)
+      # Returns true when the given path is tracked and present on the current HEAD.
+      # We use git ls-files so the check respects the index/HEAD rather than the
+      # working tree alone.
+      system("git", "ls-files", "--error-unmatch", path, out: File::NULL, err: File::NULL)
+    end
+
+    # ---------------------------------------------------------------------
+    # Command mapping table
+    #
+    # Each entry is a hash with:
+    #   :name        - the spwn subcommand students type
+    #   :help        - a short child-friendly description
+    #   :usage       - a short usage hint
+    #   :handler     - a callable that receives the remaining arguments
+    #
+    # Keeping this table in one place is deliberate: it is the single place
+    # to look when you want to add or change a command.
+    # ---------------------------------------------------------------------
+
+    COMMANDS = {
+      init: {
+        name: "init",
+        help: "Start a new project folder that Git can track.",
+        usage: "spwn init",
+        handler: ->(args) { git("init", *args) }
+      },
+
+      save: {
+        name: "save",
+        help: "Take a snapshot of your work. First pick which files to include, then give your snapshot a note.",
+        usage: "spwn save <files...> -m 'your note'   or   spwn save -m 'your note'",
+        handler: ->(args) {
+          message, _rest = extract_message_from_args(args)
+          if message.nil? || message.empty?
+            error("Tell spwn what you changed with -m, like: spwn save -m 'added a score'")
+            next nil
+          end
+
+          if ask_yes_no("Save all the changed files in this folder?")
+            git("add", ".")
+            git("commit", "-m", message)
+          else
+            say("Save cancelled. You can pick files one by one with spwn add.")
+            1
+          end
+        }
+      },
+
+      add: {
+        name: "add",
+        help: "Tell Git which files to include in the next snapshot.",
+        usage: "spwn add <file>...   or   spwn add .   or   spwn add -A",
+        handler: ->(args) {
+          files = files_from_args(args, allow_all: true)
+          git("add", *files)
+        }
+      },
+
+      commit: {
+        name: "commit",
+        help: "Save the files you have already picked. You must include a note with -m.",
+        usage: "spwn commit -m 'your note'",
+        handler: ->(args) {
+          message, _rest = extract_message_from_args(args)
+          if message.nil? || message.empty?
+            error("Every save needs a note. Try: spwn commit -m 'made the hero jump'")
+            next nil
+          end
+          git("commit", "-m", message)
+        }
+      },
+
+      look: {
+        name: "look",
+        help: "See what is going on in your project right now.",
+        usage: "spwn look",
+        handler: ->(args) { git("status", *args) }
+      },
+
+      compare: {
+        name: "compare",
+        help: "See what changed since the last snapshot.",
+        usage: "spwn compare   or   spwn compare <file>",
+        handler: ->(args) { git("diff", *args) }
+      },
+
+      history: {
+        name: "history",
+        help: "Replay the story of your project, one snapshot at a time.",
+        usage: "spwn history   or   spwn history -n 5",
+        handler: ->(args) { git("log", *args) }
+      },
+
+      hop: {
+        name: "hop",
+        help: "Jump to another universe (branch) or bring back a file from another snapshot.",
+        usage: "spwn hop <branch>   or   spwn hop -- <branch> <file>",
+        handler: ->(args) {
+          if args.empty?
+            error("Where should we hop? Try a branch name, or use spwn hop -- <branch> <file> to restore a file.")
+            next nil
+          end
+
+          if args[0] == "--"
+            rest = args[1..]
+            if rest.nil? || rest.empty?
+              error("What should we restore? Try: spwn hop -- main my_level.rb")
+              next nil
+            end
+
+            if rest.length == 1
+              # Only one thing after --: could be a branch or a file.
+              # If it is a file that exists on the current HEAD, restore it from here.
+              # Otherwise ask for the source branch explicitly.
+              candidate = rest[0]
+              if file_on_head?(candidate)
+                next git("restore", "--", candidate)
+              else
+                error("I cannot tell which universe to pull #{candidate} from. Try: spwn hop -- <branch> #{candidate}")
+                next nil
+              end
+            else
+              # branch followed by one or more files
+              source_branch = rest[0]
+              files = rest[1..]
+              if files.nil? || files.empty?
+                error("Which file should we bring back from #{source_branch}? Try: spwn hop -- #{source_branch} my_level.rb")
+                next nil
+              end
+              next git("restore", "--source", source_branch, "--", *files)
+            end
+          end
+
+          git("switch", *args)
+        }
+      },
+
+      upload: {
+        name: "upload",
+        help: "Send your snapshots to the shared project space.",
+        usage: "spwn upload   or   spwn upload <branch>",
+        handler: ->(args) { git("push", *args) }
+      },
+
+      download: {
+        name: "download",
+        help: "Fetch new snapshots from the shared project space and combine them with yours.",
+        usage: "spwn download   or   spwn download <remote> <branch>",
+        handler: ->(args) { git("pull", *args) }
+      },
+
+      sync: {
+        name: "sync",
+        help: "Copy a lesson folder into your game folder. The first time a lesson touches a file that already exists in your game folder, spwn asks before replacing it. After you accept a file, later lessons upgrade that same file automatically, so asset updates get easier as you go.",
+        usage: "spwn sync <lesson-folder> --into <game-folder>   or   spwn sync <lesson-folder> --into <game-folder> --force",
+        handler: ->(args) { require_relative "synchronizer"; Spawnpoint::Synchronizer.new.run(args) }
+      },
+
+      rollback: {
+        name: "rollback",
+        help: "Undo the most recent lesson sync.",
+        usage: "spwn rollback --into <game-folder>",
+        handler: ->(args) { require_relative "synchronizer"; Spawnpoint::Synchronizer.new.rollback(args) }
+      }
+    }.freeze
+
+    SUBCOMMANDS = COMMANDS.values.freeze
+
+    # ---------------------------------------------------------------------
+    # Help text
+    # ---------------------------------------------------------------------
+
+    def print_help
+      say("spwn v#{VERSION}")
+      say("A friendly face for Git, made for learning game programming.")
+      say("")
+      say("Usage:")
+      say("  spwn <command> [options]")
+      say("")
+      say("Commands:")
+      SUBCOMMANDS.sort_by { |c| c[:name] }.each do |cmd|
+        say("  #{cmd[:name].to_s.ljust(12)} #{cmd[:help]}")
+      end
+      say("")
+      say("Tips:")
+      say("  - Run spwn <command> --help to see Git's own help for that command.")
+      say("  - You can still use git directly when you are ready.")
+      say("  - spwn save is a shortcut for adding changed files and committing them together.")
+    end
+
+    def print_command_help(command_name)
+      cmd = COMMANDS[command_name]
+      if cmd.nil?
+        error("I do not know that command. Run spwn --help to see the list.")
+        return
+      end
+
+      say("spwn #{cmd[:name]}")
+      say("")
+      say(cmd[:help])
+      say("")
+      say("Usage:")
+      say("  #{cmd[:usage]}")
+    end
+
+    # ---------------------------------------------------------------------
+    # Dispatch
+    # ---------------------------------------------------------------------
+
+    # Runs the CLI and returns an Integer exit code.
+    #
+    # Handlers return an Integer exit code, or true/false from `system`.
+    # Integers pass through, `true` maps to 0, and everything else (false, nil)
+    # maps to 1, so misuse and Git failures exit non-zero.
+    def run(argv)
+      command_name = argv[0]
+
+      if command_name.nil? || command_name == "--help" || command_name == "-h"
+        print_help
+        return 0
+      end
+
+      if command_name == "--version" || command_name == "-v"
+        say("spwn v#{VERSION}")
+        return 0
+      end
+
+      command_key = command_name.to_sym
+      cmd = COMMANDS[command_key]
+
+      unless cmd
+        error("I do not know that command: #{command_name}")
+        say("Run spwn --help to see the commands I do know.")
+        return 1
+      end
+
+      command_args = argv[1..] || []
+
+      if command_args_include_help?(command_args)
+        print_command_help(command_key)
+        if git_command_exists?(command_key.to_s)
+          git(command_key.to_s, *command_args)
+        else
+          say("")
+          say("Git does not have a #{command_key} command, so there is no extra help to show beyond this.")
+        end
+        return 0
+      end
+
+      normalize_exit(cmd[:handler].call(command_args))
+    end
+
+    def normalize_exit(result)
+      case result
+      when Integer then result
+      when true then 0
+      else 1
+      end
+    end
+  end
+end

data/lib/spawnpoint/synchronizer.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+# Synchronizer implements `spwn sync`.
+#
+# It copies a lesson source folder into a DragonRuby game folder (usually
+# mygame/). It is intentionally a copy tool, not a Git command: the course
+# materials are distributed as folders, and the student's game folder is the
+# place where DragonRuby loads them.
+#
+# Design notes:
+#
+# - Source is a directory, not a single file. Lessons are more than one file
+#   once assets enter the picture.
+# - Existing files are never overwritten without the student saying so. This
+#   matters most for assets: a later lesson may ship a better sprite, and the
+#   student should choose whether to replace the older one.
+# - When the source contains an assets/ folder, the sync prints a reminder that
+#   assets are part of this lesson and may change between lessons.
+
+require "fileutils"
+require "pathname"
+require "set"
+
+module Spawnpoint
+  class Synchronizer
+    BACKUP_DIR = ".spwn_sync_backup"
+
+    def run(argv)
+      lesson_folder, into_folder, force = parse_args(argv)
+
+      unless lesson_folder
+        puts "Usage:"
+        puts "  spwn sync <lesson-folder> --into <game-folder>"
+        puts "  spwn sync <lesson-folder> --into <game-folder> --force"
+        puts ""
+        puts "Example:"
+        puts "  spwn sync 04-collectibles/starter --into ~/DragonRuby/mygame"
+        puts ""
+        puts "The first time a lesson copies a file that already exists in your"
+        puts "game folder, spwn asks before replacing it. After you accept a"
+        puts "file, later lessons replace that same file automatically."
+        return 1
+      end
+
+      unless into_folder
+        puts "Oops: tell spwn where to copy the lesson with --into."
+        puts "Example: spwn sync 04-collectibles/starter --into ~/DragonRuby/mygame"
+        return 1
+      end
+
+      source = Pathname.new(lesson_folder).expand_path
+      target = Pathname.new(into_folder).expand_path
+
+      unless source.directory?
+        puts "Oops: #{source} is not a folder."
+        return 1
+      end
+
+      unless target.directory?
+        puts "Oops: #{target} is not a folder yet."
+        return 1
+      end
+
+      has_assets = source.join("assets").directory?
+
+      if has_assets
+        puts "This lesson includes an assets/ folder."
+        puts "Assets may look different from the previous lesson."
+        puts "If you already have sprites from an older lesson, you will be asked before each one is replaced."
+        puts ""
+      end
+
+      marker = target.join(".spwn_synced_paths")
+      backup = target.join(BACKUP_DIR)
+      FileUtils.rm_rf(backup)
+      backup.join("files").mkpath
+      backup.join("created_paths").write("")
+      if marker.file?
+        FileUtils.cp(marker, backup.join("marker"))
+      else
+        backup.join("no_marker").write("")
+      end
+
+      known = if marker.file?
+        marker.readlines.map(&:strip).reject(&:empty?).to_set
+      else
+        Set.new
+      end
+
+      already_existed = Set.new
+      target.find.each do |child|
+        next unless child.file?
+        already_existed << child.relative_path_from(target).to_s
+      end
+
+      copied = 0
+      upgraded = 0
+      skipped = 0
+      new_known = Set.new
+
+      source.find.to_a.each do |child|
+        next unless child.file?
+
+        rel = child.relative_path_from(source)
+        rel_s = rel.to_s
+        dest = target.join(rel)
+
+        if dest.exist?
+          if force || known.include?(rel_s)
+            backup_existing(backup, dest, rel_s)
+            copy_file(child, dest)
+            upgraded += 1
+            new_known << rel_s
+          elsif already_existed.include?(rel_s)
+            if agree?("Copy #{rel} from this lesson?")
+              backup_existing(backup, dest, rel_s)
+              copy_file(child, dest)
+              upgraded += 1
+              new_known << rel_s
+            else
+              skipped += 1
+            end
+          end
+        else
+          copy_file(child, dest)
+          File.open(backup.join("created_paths"), "a") { |fh| fh.puts(rel_s) }
+          copied += 1
+          new_known << rel_s
+        end
+      end
+
+      merged = known | new_known
+      if merged.any?
+        marker.open("w") do |fh|
+          merged.to_a.sort.each do |name|
+            fh.puts(name)
+          end
+        end
+      end
+
+      puts ""
+      puts "Done."
+      puts "New:       #{copied}"
+      puts "Updated:   #{upgraded}"
+      puts "Skipped:   #{skipped}"
+
+      0
+    end
+
+    def rollback(argv)
+      target = parse_rollback_args(argv)
+      unless target
+        puts "Usage: spwn rollback --into <game-folder>"
+        return 1
+      end
+
+      target = Pathname.new(target).expand_path
+      backup = target.join(BACKUP_DIR)
+      unless backup.directory?
+        puts "Oops: there is no lesson sync to roll back in #{target}."
+        return 1
+      end
+
+      backup.join("created_paths").readlines.each do |line|
+        target.join(line.strip).delete if !line.strip.empty? && target.join(line.strip).file?
+      end
+      backup.join("files").find do |saved|
+        next if saved.directory? || saved == backup.join("files")
+        rel = saved.relative_path_from(backup.join("files"))
+        dest = target.join(rel)
+        FileUtils.mkdir_p(dest.parent)
+        FileUtils.cp(saved, dest)
+      end
+
+      marker = target.join(".spwn_synced_paths")
+      if backup.join("marker").file?
+        FileUtils.cp(backup.join("marker"), marker)
+      else
+        marker.delete if marker.file?
+      end
+
+      FileUtils.rm_rf(backup)
+      puts "Rolled back the most recent lesson sync."
+      0
+    end
+
+    private
+
+    def parse_args(argv)
+      lesson_folder = nil
+      into_folder = nil
+      force = false
+
+      i = 0
+      while i < argv.length
+        arg = argv[i]
+        case arg
+        when "--into"
+          i += 1
+          into_folder = argv[i]
+        when "--force", "-f"
+          force = true
+        when /\A-/
+          puts "Oops: I do not understand #{arg}."
+          return [nil, nil, false]
+        else
+          lesson_folder ||= arg
+        end
+        i += 1
+      end
+
+      [lesson_folder, into_folder, force]
+    end
+
+    def parse_rollback_args(argv)
+      i = argv.index("--into")
+      i && argv[i + 1]
+    end
+
+    def backup_existing(backup, dest, rel)
+      saved = backup.join("files", rel)
+      FileUtils.mkdir_p(saved.parent)
+      FileUtils.cp(dest, saved)
+    end
+
+    def copy_file(source, dest)
+      FileUtils.mkdir_p(dest.parent)
+      FileUtils.cp(source, dest)
+    end
+
+    def agree?(question)
+      loop do
+        print "#{question} (y/n): "
+        answer = STDIN.gets
+        return false if answer.nil?
+
+        answer = answer.strip.downcase
+        return true if answer == "y"
+        return false if answer == "n"
+        puts "Please type y or n."
+      end
+    end
+  end
+end

data/lib/spawnpoint/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Spawnpoint
+  VERSION = "0.2.0"
+end

data/lib/spawnpoint.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "spawnpoint/version"
+require_relative "spawnpoint/cli"

data/spawnpoint.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "lib/spawnpoint/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "spawnpoint"
+  spec.version = Spawnpoint::VERSION
+  spec.authors = ["bebekim"]
+  spec.summary = "A child-friendly Git mask for learning game programming"
+  spec.description = "spwn is a thin wrapper around Git that renames Git " \
+                     "commands into friendlier, game-like language for kids " \
+                     "learning game programming."
+  spec.homepage = "https://github.com/bebekim/spawnpoint"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.bindir = "exe"
+  spec.executables = ["spwn"]
+  spec.require_paths = ["lib"]
+
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/bebekim/spawnpoint",
+    "rubygems_mfa_required" => "true"
+  }
+end

data/test/test_cli.rb

@@ -0,0 +1,38 @@
+require "test_helper"
+require "spawnpoint/cli"
+
+class TestCli < Minitest::Test
+  def run_cli(argv)
+    capture_io { @status = Spawnpoint::CLI.run(argv) }
+    @status
+  end
+
+  def test_no_arguments_prints_help_and_exits_zero
+    assert_equal 0, run_cli([])
+  end
+
+  def test_help_flag_exits_zero
+    assert_equal 0, run_cli(["--help"])
+  end
+
+  def test_version_flag_exits_zero
+    out, = capture_io { Spawnpoint::CLI.run(["--version"]) }
+    assert_includes out, "0.2.0"
+  end
+
+  def test_unknown_command_exits_one
+    assert_equal 1, run_cli(["teleport"])
+  end
+
+  def test_save_without_message_exits_one
+    assert_equal 1, run_cli(["save"])
+  end
+
+  def test_commit_without_message_exits_one
+    assert_equal 1, run_cli(["commit"])
+  end
+
+  def test_hop_without_arguments_exits_one
+    assert_equal 1, run_cli(["hop"])
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "minitest/autorun"