spawnpoint 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ae1f2aae6f8340c03f309364e62b1b78113eff6aab8fcd6ba61ba416cf028b7
+  data.tar.gz: caa9708a4ff55754b5643f107a0bf09fb64b2e736da36986bc23c0babc46da89
+SHA512:
+  metadata.gz: bc35e776bfca6667e159e4d8b7a5d6f78378b26a0d4d8ffcd0ad0cae32cef918ae168ec247a39301606767d8df496ca3923c5cc9b5fac9ca28b5aebcbb7974e5
+  data.tar.gz: aaf1371dea70274993ab2b3b10efdd2c777b05c6ae005cb703b2681e8d0f0d894a0048b34a167e8d2a40ccef9d4df004514fc374c52a5bb7de2c02f464d23228

data/.gitignore

@@ -0,0 +1,5 @@
+.claude
+.agent-learning
+*.gem
+/pkg/
+/Gemfile.lock

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest", "~> 5.0"
+gem "rake", "~> 13.0"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bebekim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+# spwn
+
+A child-friendly text interface for Git, aimed at 12-year-olds learning to program games.
+
+`spwn` is a thin wrapper around Git that renames the commands into game-like language and
+presents them through a simple command-line interface. It is not a replacement for Git; it is
+a mask that makes the vocabulary friendlier while still calling Git under the hood.
+
+## Before you start
+
+`spwn` needs two things already installed: **Ruby** and **Git**. It does not install either of
+them for you.
+
+Check whether you have them by running:
+
+```bash
+ruby --version
+git --version
+```
+
+If both commands print a version number, you are ready to go. If one of them says "command not
+found", install the missing piece first.
+
+- **Ruby** — from `https://www.ruby-lang.org/`. On Windows, the RubyInstaller2 downloads are at
+  `https://github.com/oneclick/rubyinstaller2/releases`; pick the latest release and use the
+  installer that matches your machine (the plain installer is enough if you do not need to compile
+  C extensions).
+- **Git** — from `https://git-scm.com/`. On macOS, Git may already be available; if not,
+  `xcode-select --install` is one common way to get it. On Windows, the Git installer from
+  `git-scm.com` puts Git on your PATH.
+
+Once Ruby and Git are installed, `spwn` itself is one `gem install` away.
+
+## Philosophy
+
+- Friendlier words, not a new VCS. Git still does the real work.
+- Thin confirmations. Dangerous operations still go through Git's normal behavior; we do not
+  add extra popups unless a command genuinely needs a "are you sure?" step.
+- Easy to extend. The mapping between `spwn` commands and Git invocations lives inside
+  `lib/spawnpoint/cli.rb` so students and instructors can add or change commands in one place.
+- Standard Git still works. Students can always fall back to `git` directly when they are ready.
+
+## Quick start
+
+Install the gem and run `spwn`:
+
+```bash
+gem install spawnpoint
+spwn --help
+```
+
+To run the latest code from this repository instead:
+
+```bash
+ruby -Ilib exe/spwn --help
+```
+
+## Installing for a student
+
+`spwn` is published as the `spawnpoint` gem, so installation is the same on macOS
+and Windows once Ruby is installed:
+
+```bash
+gem install spawnpoint
+```
+
+This puts the `spwn` command on the PATH. Updating later is `gem update spawnpoint`.
+
+If a machine cannot reach rubygems.org, build the gem from this repository and
+install the file directly:
+
+```bash
+gem build spawnpoint.gemspec
+gem install --local ./spawnpoint-0.2.0.gem
+```
+
+## Command mapping
+
+`spwn` is a thin rename layer over Git. The table below shows the main mappings. When a student
+is ready, they can use the Git command directly instead.
+
+| `spwn` command | Git command(s) | What it does |
+| --- | --- | --- |
+| `spwn init` | `git init` | Start a new project folder that Git can track. |
+| `spwn add <file>` | `git add <file>` | Tell Git which files to include in the next snapshot. |
+| `spwn add .` | `git add .` | Stage all changed files in the current folder. |
+| `spwn add -A` | `git add -A` | Stage all changed files, including deletions. |
+| `spwn commit -m 'note'` | `git commit -m 'note'` | Save the files you have already picked. |
+| `spwn save -m 'note'` | `git add .` then `git commit -m 'note'` | Stage changed files and commit them together. |
+| `spwn look` | `git status` | See what is going on in your project right now. |
+| `spwn compare` | `git diff` | See what changed since the last snapshot. |
+| `spwn history` | `git log` | Replay the story of your project, one snapshot at a time. |
+| `spwn hop <branch>` | `git switch <branch>` | Jump to another universe (branch). |
+| `spwn hop -- <branch> <file>` | `git restore --source <branch> -- <file>` | Bring a file back from another snapshot. |
+| `spwn upload` | `git push` | Send your snapshots to the shared project space. |
+| `spwn download` | `git pull` | Fetch new snapshots from the shared project space and combine them with yours. |
+| `spwn sync <lesson> --into <game>` | — | Copy lesson files into a game folder, replacing matching files when confirmed. |
+| `spwn rollback --into <game>` | — | Undo the most recent lesson sync: restore replaced files and remove newly copied files. |
+
+A few notes about the mapping:
+
+- `spwn save` is the only command that runs more than one Git command. It stages the current
+  folder and then commits, so students can think of it as "save everything with a note".
+- `spwn hop --` is the file-restore form. The branch must be named explicitly, for example
+  `spwn hop -- feature my_level.rb`. If you give only a file name and that file already exists on
+  the current branch, `spwn` restores it from there; otherwise it asks you to name the source
+  branch.
+- `spwn` does not hide Git's errors on purpose. If something goes wrong, the error still comes
+  from Git, so students eventually see the real message behind the friendly name.
+
+## Commands
+
+Run `spwn --help` for the current list. The first version focuses on the commands
+students need while following a single-player course:
+
+- `spwn save` — stage changed files and commit them together.
+- `spwn add` — stage files. Supports individual paths, `.`, and `-A`.
+- `spwn commit` — commit already staged changes.
+- `spwn look` — inspect the current state.
+- `spwn compare` — show what changed.
+- `spwn history` — show recent commits.
+- `spwn hop` — switch branches or restore files.
+- `spwn upload` — push to a remote.
+- `spwn download` — fetch and integrate from a remote.
+- `spwn init` — start a new project.
+- `spwn sync <lesson> --into <game>` — copy lesson files into a game folder. Use `--force` to
+  replace matching files without asking.
+- `spwn rollback --into <game>` — undo the most recent sync. Files that existed before the sync
+  are restored, files created by the sync are removed, and unrelated game files are left alone.
+
+Branch-related commands are framed as "multiverse" because branches feel like parallel universes
+to a 12-year-old. `spwn hop` is the entry point for both switching branches and restoring files;
+the script explains the difference in its help text.
+
+## Extending the mapping
+
+Open `lib/spawnpoint/cli.rb` and look for the command mapping table near the top of the file. Each entry
+describes:
+
+- the `spwn` subcommand name,
+- the help text shown to students,
+- the Git command or commands to run,
+- any flags or argument handling.
+
+To add a new command, add a row to that table and, if needed, a small amount of argument handling
+code nearby. To change how an existing command works, edit its row. You do not need to touch the
+main dispatch logic unless you are changing how arguments flow through the script.
+
+## Relationship to the course
+
+This tool is intentionally small. It is designed to be used alongside the course materials, not
+to become a project of its own. If a lesson needs a new Git workflow, add the corresponding
+`spwn` command rather than building a separate tool.

data/Rakefile

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

data/docs/2026-08-14-spawnpoint-gem-design.md

@@ -0,0 +1,90 @@
+# Package spwn as the `spawnpoint` Ruby gem
+
+**Status:** approved 2026-08-14
+**Target release:** v0.2.0 (v0.1.0 is already tagged and released on GitHub)
+
+## Goal
+
+Students install the tool with `gem install spawnpoint` and run `spwn`. The gem
+name `spwn` is taken on rubygems.org (unrelated 2012 gem); `spawnpoint` is free.
+The executable stays `spwn` regardless of gem name.
+
+## Decisions
+
+- Publish to rubygems.org as `spawnpoint` (executable: `spwn`).
+- Standard gem layout (hand-written gemspec, no `bundle gem` scaffold).
+- The three review findings from the v0.1.0 review are fixed in this pass.
+
+## Architecture
+
+```
+spawnpoint.gemspec      # hand-written; executables ["spwn"], bindir "exe"
+Gemfile                 # gemspec + dev dependencies only
+Rakefile                # default task: test
+LICENSE                 # MIT
+exe/spwn                # require "spawnpoint/cli"; exit Spawnpoint::CLI.run(ARGV)
+lib/spawnpoint.rb       # entry point; requires version + cli
+lib/spawnpoint/version.rb  # Spawnpoint::VERSION = "0.2.0"
+lib/spawnpoint/cli.rb   # command table, dispatch, help (moved from bin/spwn)
+lib/spawnpoint/synchronizer.rb  # moved from bin/__sync__.rb, class renamed
+test/                   # minitest suite
+```
+
+- Module namespace is `Spawnpoint` (matches gem name convention).
+- `bin/spwn` and `bin/__sync__.rb` are deleted; their code moves into `lib/`.
+- No runtime dependencies — Ruby stdlib only (`fileutils`, `pathname`, `set`).
+
+## Bug fixes folded in
+
+1. **Exit-code propagation** — today `bin/spwn:322-323` calls the handler and
+   always returns 0. New contract: handlers return an Integer exit code or a
+   boolean (from `system`); the dispatcher normalizes to an Integer and
+   `Spawnpoint::CLI.run` returns it. `spwn sync` misuse and git command failures
+   exit non-zero.
+2. **Marker merge** — `.spwn_synced_paths` is written as the union of previously
+   known paths and this sync's paths (`known | new_known`), so files accepted in
+   earlier lessons are not re-prompted later.
+3. **Rename and cleanup** — `Syncronizer` → `Synchronizer`; the dead
+   auto-replace branch and the no-op `next if child == ...` guards are removed.
+
+## Packaging details
+
+- Gemspec: name `spawnpoint`, version from `Spawnpoint::VERSION`, files from
+  `git ls-files`, homepage `https://github.com/bebekim/spawnpoint`,
+  license `MIT`, `required_ruby_version >= 3.0` (uses `argv[1..]`).
+- `Gemfile` contains `gemspec` plus dev dependencies (minitest, rake).
+- MIT `LICENSE` file added (gemspec requires a license for a clean push).
+
+## Testing
+
+Minitest (stdlib, no new runtime deps) in `test/`:
+
+- CLI: unknown command exits 1; sync with missing args exits non-zero; `--help`
+  exits 0.
+- Synchronizer: fresh copy into a game folder; overwrite-with-confirmation;
+  `--force`; rollback restores replaced files and removes created ones; marker
+  union across two lessons (accepted file from lesson 1 is not re-prompted in
+  lesson 3).
+
+## README changes
+
+- Install section: `gem install spawnpoint`, then `spwn --help`.
+- Quick start for repo development: `ruby -Ilib exe/spwn --help`.
+- Remove the PATH-shim section (obsolete — the gem puts `spwn` on PATH).
+- Command mapping table and sync/rollback docs unchanged.
+
+## Release flow (after implementation lands)
+
+1. Commit, tag `v0.2.0`, push.
+2. `gem build spawnpoint.gemspec` → `spawnpoint-0.2.0.gem`.
+3. GitHub release `v0.2.0` (attach the `.gem` optional).
+4. `gem push spawnpoint-0.2.0.gem` — requires the maintainer's rubygems.org
+   credentials; run by the maintainer or with an API key provided at that time.
+
+## Out of scope
+
+- Homebrew formula, Scoop/WinGet manifests (README future-ideas list).
+- The untracked pipeline/agent scaffolding (`spec.md`, `plan.json`,
+  `pipeline-config.json`, `runs/`, `artifacts/`, `.agent-learning/`, `.claude/`)
+  — left out of the gem via `git ls-files`; a separate decision whether they
+  belong in the repo at all.