smart_box 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdd527c54db2a72e0d40528a4fb248a712f06a8f28bd11e7b81c995963e1a4e1
+  data.tar.gz: b277525806bbccc5ad7a979733d0e9fcaa7ad483f8c8910e5d5105ea78f94712
+SHA512:
+  metadata.gz: 61675f220c4dda1cae98b9091201057351b9abd65dfe4d4c4c906aa4be4e926e0091619079034a88fdb8209c17e7fc434014b432bb8397b869fcddd413c40ca2
+  data.tar.gz: b14f1b4116d23c01e540eac1275a5048e8decc279034ee33fde8f5b374314402fb2ec0a291a20762cef9e553a1c992425bdb9c19509f2b7bc51ec21371b8c268

data/README.md

@@ -0,0 +1,144 @@
+# smart_box
+
+## What is smart_box?
+
+smart_box is a local reversible sandbox system for Coding Agent task execution.
+
+Its core goal: allow Coding Agents (SmartExpert, SmartCoder, etc.) to perform file
+modifications, command execution, dependency installation, experimental fixes, code
+generation, diff viewing, checkpoint rollback, and patch export — without directly
+polluting the real project directory.
+
+## Why smart_box?
+
+When a Coding Agent runs autonomously, it may:
+
+- Modify source files incorrectly
+- Install conflicting dependencies
+- Remove critical files
+- Produce untested patches
+
+smart_box provides a safety net: every operation happens inside an isolated box
+first. The user can inspect, verify, and then explicitly apply changes to the
+real project.
+
+## Installation
+
+```bash
+gem install smart_box
+```
+
+Or via Bundler:
+
+```ruby
+gem "smart_box"
+```
+
+## Quick Start
+
+```bash
+# Create a box from current project (copy mode)
+smart_box create --source . --id task-001 --mode copy
+
+# Run a command inside the box
+smart_box run --id task-001 -- bundle install
+
+# Create a checkpoint
+smart_box checkpoint --id task-001 --name "after bundle install"
+
+# View changes
+smart_box diff --id task-001
+
+# Export patch
+smart_box export-patch --id task-001 --output fix.patch
+
+# Rollback to initial state
+smart_box rollback --id task-001 --checkpoint cp-001 --mode copy
+
+# Apply to source project
+smart_box apply --id task-001
+
+# Discard the box
+smart_box discard --id task-001
+```
+
+## Concepts
+
+- **Source Project**: The original project directory. smart_box never modifies it directly.
+- **Box**: An isolated execution space for one task or experiment.
+- **Checkpoint**: A saved state inside a box, allowing rollback.
+- **Diff**: Changes between the box's current state and a reference point.
+- **Patch**: A portable changeset exported from a box for manual review and application.
+
+## CLI Usage
+
+```
+smart_box <command> [options]
+```
+
+| Command       | Description                          |
+|---------------|--------------------------------------|
+| create        | Create a new box                     |
+| list          | List all boxes                       |
+| status        | Show box status                      |
+| run           | Execute a command inside a box       |
+| checkpoint    | Create a checkpoint                  |
+| checkpoints   | List checkpoints in a box            |
+| rollback      | Rollback to a checkpoint             |
+| diff          | Show diff against checkpoint         |
+| export-patch  | Export patch to a file               |
+| apply         | Apply box changes to source project  |
+| discard       | Discard a box and its workspace      |
+
+## Ruby API Usage
+
+```ruby
+require "smart_box"
+
+box = SmartBox::Box.create(
+  source: ".",
+  id: "task-001",
+  mode: :copy,
+  name: "fix bundler conflict"
+)
+
+result = box.run("bundle install")
+box.checkpoint("after bundle install")
+puts box.diff
+box.rollback("cp-001")
+box.export_patch("fix.patch")
+box.apply(dry_run: true)
+```
+
+## Modes
+
+### copy mode
+
+Copies the source project (excluding `.git`, `node_modules`, etc.) into an
+isolated workspace. Simple and works even if the source is not a git repository.
+
+### git-worktree mode
+
+Uses `git worktree add` to create an isolated working directory. Faster for
+large projects and natively compatible with git workflows.
+
+## Safety Notes
+
+- Dangerous commands (`rm -rf /`, `sudo`, etc.) are blocked by default.
+- All commands are restricted to the box workspace.
+- The source project is never modified without explicit `apply`.
+- All paths use absolute normalization to prevent path traversal.
+
+## Roadmap
+
+- [x] copy mode
+- [x] git-worktree mode
+- [ ] Docker / DevContainer mode
+- [ ] Command policy configuration
+- [ ] Network policy
+- [ ] Resource limits
+- [ ] Concurrent boxes
+- [ ] SmartExpert TUI integration
+- [ ] SmartCoder workflow integration
+- [ ] MCP tool wrapper
+- [ ] JSON-RPC server mode

data/bin/smart_box

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/smart_box"
+require_relative "../lib/smart_box/cli"
+
+SmartBox::CLI.run(ARGV)

data/lib/smart_box/box.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "errors"
+require_relative "metadata"
+require_relative "modes/copy_mode"
+
+module SmartBox
+  class Box
+    attr_reader :id, :source_path, :workspace_path, :mode, :metadata
+
+    SMART_BOX_DIR = ".smart_box"
+    BOXES_DIR     = File.join(SMART_BOX_DIR, "boxes")
+
+    def initialize(source_path:, id:, mode:, name: nil)
+      @id          = id
+      @mode        = mode.to_s
+      @source_path = File.expand_path(source_path)
+      @name        = name
+      @box_dir     = File.join(@source_path, BOXES_DIR, @id)
+      @workspace_path = File.join(@box_dir, "workspace")
+      @metadata_path  = File.join(@box_dir, "metadata.yml")
+      @metadata       = Metadata.new(@metadata_path)
+    end
+
+    # --- Class methods ---
+
+    def self.create(source:, id:, mode:, name: nil)
+      box = new(source_path: source, id: id, mode: mode, name: name)
+
+      if Dir.exist?(box.send(:box_dir))
+        raise BoxAlreadyExistsError, "Box '#{id}' already exists"
+      end
+
+      FileUtils.mkdir_p(box.send(:box_dir))
+      FileUtils.mkdir_p(File.join(box.send(:box_dir), "logs"))
+      FileUtils.mkdir_p(File.join(box.send(:box_dir), "patches"))
+      FileUtils.mkdir_p(File.join(box.send(:box_dir), "checkpoints"))
+
+      mode_instance = box.send(:mode_instance)
+      mode_instance.setup
+
+      # Capture initial git commit hash
+      initial_commit = box.send(:git_latest_commit)
+
+      box.metadata.id             = id
+      box.metadata.name           = name
+      box.metadata.mode           = mode.to_s
+      box.metadata.source_path    = box.source_path
+      box.metadata.workspace_path = box.workspace_path
+      box.metadata.status         = "active"
+      box.metadata.created_at     = Time.now.utc.iso8601
+      box.metadata.updated_at     = Time.now.utc.iso8601
+      box.metadata.base           = {
+        "type" => mode.to_s,
+        "source_git_commit" => box.send(:source_git_commit),
+        "source_git_branch" => box.send(:source_git_branch)
+      }
+      box.metadata.add_checkpoint(
+        id:         "cp-001",
+        name:       "initial",
+        git_commit: initial_commit,
+        created_at: Time.now.utc.iso8601
+      )
+      box.metadata.stats = {
+        "commands_count"      => 0,
+        "changed_files_count" => 0
+      }
+      box.metadata.save!
+
+      box
+    end
+
+    def self.load(source:, id:)
+      box = new(source_path: source, id: id, mode: nil)
+
+      unless Dir.exist?(box.send(:box_dir))
+        raise BoxNotFoundError, "Box '#{id}' not found"
+      end
+
+      box.metadata.load!
+
+      unless box.metadata.id
+        raise BoxNotFoundError, "Box '#{id}' metadata is missing 'id' field"
+      end
+
+      box
+    end
+
+    def self.list(source:)
+      boxes_path = File.join(File.expand_path(source), BOXES_DIR)
+      return [] unless Dir.exist?(boxes_path)
+
+      Dir.each_child(boxes_path).filter_map do |entry|
+        box_path = File.join(boxes_path, entry)
+        next unless Dir.exist?(box_path)
+
+        metadata_path = File.join(box_path, "metadata.yml")
+        next unless File.exist?(metadata_path)
+
+        meta = YAML.safe_load_file(metadata_path, permitted_classes: [Time])
+        next unless meta.is_a?(Hash)
+
+        {
+          "id"         => meta["id"] || entry,
+          "mode"       => meta["mode"] || "unknown",
+          "status"     => meta["status"] || "unknown",
+          "updated_at" => meta["updated_at"] || "unknown"
+        }
+      end
+    end
+
+    # --- Instance methods ---
+
+    def status_summary
+      {
+        "id"            => @id,
+        "mode"          => @mode || @metadata.mode,
+        "status"        => @metadata.status,
+        "workspace"     => @workspace_path,
+        "changed_files" => git_status_short,
+        "checkpoints"   => @metadata.checkpoints.map { |cp| { cp["id"] => cp["name"] } }
+      }
+    end
+
+    def git_status_short
+      return [] unless Dir.exist?(@workspace_path)
+
+      Dir.chdir(@workspace_path) do
+        out = `git status --porcelain 2>/dev/null`
+        return [] unless $?.success?
+
+        out.lines.map(&:chomp).reject(&:empty?)
+      end
+    end
+
+    def run(command, env: {}, timeout: nil, allow_dangerous: false)
+      runner.run(command, env: env, timeout: timeout, allow_dangerous: allow_dangerous).tap do
+        # Update metadata stats
+        @metadata.load!
+        stats = @metadata.stats
+        stats["commands_count"] = (stats["commands_count"] || 0) + 1
+        @metadata.updated_at = Time.now.utc.iso8601
+        @metadata.save!
+      end
+    end
+
+    def checkpoint(name)
+      raise Error, "Workspace does not exist" unless Dir.exist?(@workspace_path)
+
+      Dir.chdir(@workspace_path) do
+        system("git", "add", "-A", out: File::NULL, err: File::NULL)
+        system("git", "commit", "--allow-empty", "-m", name, out: File::NULL, err: File::NULL)
+      end
+
+      commit = git_latest_commit
+      cp_id = "cp-#{format('%03d', (@metadata.checkpoints.size + 1))}"
+
+      @metadata.load!
+      @metadata.add_checkpoint(
+        id:         cp_id,
+        name:       name,
+        git_commit: commit,
+        created_at: Time.now.utc.iso8601
+      )
+      @metadata.updated_at = Time.now.utc.iso8601
+      @metadata.save!
+
+      { id: cp_id, name: name, commit: commit }
+    end
+
+    def checkpoints
+      @metadata.load!
+      @metadata.checkpoints.map do |cp|
+        { "id" => cp["id"], "name" => cp["name"] }
+      end
+    end
+
+    def rollback(checkpoint_id)
+      cp = @metadata.checkpoints.detect { |c| c["id"] == checkpoint_id }
+      raise CheckpointNotFoundError, "Checkpoint '#{checkpoint_id}' not found" unless cp
+
+      Dir.chdir(@workspace_path) do
+        system("git", "reset", "--hard", cp["git_commit"], out: File::NULL, err: File::NULL)
+        system("git", "clean", "-fd", out: File::NULL, err: File::NULL)
+      end
+
+      @metadata.load!
+      @metadata.updated_at = Time.now.utc.iso8601
+      @metadata.save!
+
+      { box_id: @id, checkpoint_id: checkpoint_id }
+    end
+
+    def diff(from: nil, to: nil)
+      raise Error, "Workspace does not exist" unless Dir.exist?(@workspace_path)
+
+      Dir.chdir(@workspace_path) do
+        # Stage everything so untracked files appear in diff
+        system("git", "add", "-A", out: File::NULL, err: File::NULL)
+
+        from_commit = if from
+                        resolve_checkpoint_commit(from)
+                      else
+                        init = @metadata.checkpoints.first
+                        init ? init["git_commit"] : "HEAD~1"
+                      end
+
+        to_commit = to ? resolve_checkpoint_commit(to) : nil
+
+        if to_commit
+          `git diff #{from_commit} #{to_commit} 2>/dev/null`
+        else
+          `git diff --cached #{from_commit} 2>/dev/null`
+        end
+      end
+    end
+
+    def export_patch(output:, from: nil, to: nil)
+      output_path = if output.start_with?("/")
+                      output
+                    else
+                      File.join(Dir.pwd, output)
+                    end
+
+      patch_content = diff(from: from, to: to)
+      File.write(output_path, patch_content)
+
+      { output: output_path, size: patch_content.bytesize }
+    end
+
+    def apply(dry_run: false, force: false)
+      raise Error, "Workspace does not exist" unless Dir.exist?(@workspace_path)
+
+      patch_content = diff(from: @metadata.checkpoints.first&.dig("git_commit"))
+
+      if dry_run
+        return { dry_run: true, patch_size: patch_content.bytesize }
+      end
+
+      # Check if source is a git repo and if it's clean
+      if Dir.exist?(File.join(@source_path, ".git"))
+        unless force
+          check_source_clean!
+        end
+
+        # Create backup patch of current source state
+        backup_patch_path = File.join(@box_dir, "patches", "backup.patch")
+        FileUtils.mkdir_p(File.join(@box_dir, "patches"))
+
+        Dir.chdir(@source_path) do
+          backup = `git diff 2>/dev/null`
+          File.write(backup_patch_path, backup) unless backup.empty?
+        end
+
+        # Apply the patch
+        Dir.chdir(@source_path) do
+          IO.popen(["git", "apply", "-v"], "w") do |io|
+            io.write(patch_content)
+          end
+
+          unless $?.success?
+            raise PatchApplyError, "Failed to apply patch. The source project may have conflicts."
+          end
+
+          # Show what changed
+          result_diff = `git diff 2>/dev/null`
+          result_diff
+        end
+      else
+        # Non-git source: apply patch with patch command
+        backup_patch_path = File.join(@box_dir, "patches", "backup.diff")
+        FileUtils.mkdir_p(File.join(@box_dir, "patches"))
+        File.write(backup_patch_path, "backup not available for non-git source")
+
+        Dir.chdir(@source_path) do
+          IO.popen(["patch", "-p1", "-N", "-r", "/dev/null"], "w") do |io|
+            io.write(patch_content)
+          end
+        end
+
+        "Patch applied to non-git source at #{@source_path}"
+      end
+    end
+
+    def discard
+      raise Error, "Box directory does not exist" unless Dir.exist?(@box_dir)
+
+      # For git-worktree mode, remove the worktree first
+      if %w[git-worktree git_worktree].include?(@metadata.mode)
+        mode_instance.teardown
+      end
+
+      FileUtils.rm_rf(@box_dir)
+      @metadata.status = "discarded"
+      { id: @id, status: "discarded" }
+    end
+
+    def source_clean?
+      return true unless Dir.exist?(File.join(@source_path, ".git"))
+      Dir.chdir(@source_path) { `git status --porcelain 2>/dev/null`.strip.empty? }
+    end
+
+    private
+
+    attr_reader :box_dir, :metadata_path
+
+    def runner
+      @runner ||= Runner.new(
+        box_id:         @id,
+        workspace_path: @workspace_path,
+        logs_dir:       File.join(@box_dir, "logs")
+      )
+    end
+
+    def mode_instance
+      current_mode = @mode.to_s.empty? ? @metadata.mode.to_s : @mode.to_s
+
+      case current_mode
+      when "copy"
+        Modes::CopyMode.new(
+          source_path:    @source_path,
+          workspace_path: @workspace_path
+        )
+      when "git-worktree", "git_worktree"
+        Modes::GitWorktreeMode.new(
+          source_path: @source_path, workspace_path: @workspace_path, box_id: @id
+        )
+      else
+        raise InvalidModeError, "Unknown mode: #{current_mode}"
+      end
+    end
+
+    def git_latest_commit
+      # In git-worktree mode the workspace's `.git` is a FILE (a gitdir
+      # pointer), not a directory — so Dir.exist? is false and this would
+      # wrongly return "none". File.exist? is true for both files and dirs.
+      return "none" unless File.exist?(File.join(@workspace_path, ".git"))
+
+      Dir.chdir(@workspace_path) do
+        `git rev-parse HEAD 2>/dev/null`.strip
+      end
+    end
+
+    def source_git_commit
+      git_dir = File.join(@source_path, ".git")
+      return "none" unless Dir.exist?(git_dir)
+
+      Dir.chdir(@source_path) do
+        `git rev-parse HEAD 2>/dev/null`.strip
+      end
+    end
+
+    def source_git_branch
+      git_dir = File.join(@source_path, ".git")
+      return "none" unless Dir.exist?(git_dir)
+
+      Dir.chdir(@source_path) do
+        `git rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
+      end
+    end
+
+    def resolve_checkpoint_commit(checkpoint_id)
+      cp = @metadata.checkpoints.detect { |c| c["id"] == checkpoint_id }
+      if cp
+        cp["git_commit"]
+      else
+        checkpoint_id
+      end
+    end
+
+    def check_source_clean!
+      unless source_clean?
+        raise DirtySourceError,
+          "Source project has uncommitted changes.\n" \
+          "Use --force to apply anyway."
+      end
+    end
+  end
+end