lex-exec 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b3366ef2850eb31f9ac4e550547c509a2742c4d7905baa5e7785659144d7422
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: ce39d50a81ab331806b98ec1790aac9581d34425ea262d2beba00b88d0871536
+  data.tar.gz: d9c0e98ac019d2989d786444bf6b18175f64a811d8e543b5800e8800738693ea
 SHA512:
-  metadata.gz: 0b2eb12cff14bf96642ce20f6799bd985a9e8d07afe1947d557dd9f589df4e2625a4725abf33f41b71d0b03febfcdd196cf819b388431af543507a37c06421eb
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: b41990118730fea1147ee66c270b49a34d1fedab7fdb347dfe0f71716a4959aecbacebf79c63fecd5e63dcf184b8f44ca99c7aafcc6c1267b749aed856d56550
+  data.tar.gz: 4346cb561525e40ad698a2f66746714f331cbb1296bc87af18c796eb08c079fce0db6a463bb57a3b4bfc0ec4281c9411d39d97e06e67d80c1e6fae15f8bc6d55

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,56 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.1.3] - 2026-03-20
+
+### Fixed
+- Gemspec missing `spec.files` declaration — gem build previously produced an empty gem with no files
+- Entry point missing `require_relative` for `Helpers::Checkpoint` and `Helpers::Worktree`
+
+## [0.1.2] - 2026-03-20
+
+### Added
+- `Helpers::Worktree` for git worktree creation, removal, and listing
+- `Helpers::Checkpoint` for hidden-ref-based state snapshots and restore
+
+## [0.1.1] - 2026-03-18
+
+### Fixed
+- `Git.push` default branch changed from `'master'` to `'main'` to match GitHub's default since 2020
+
+## [0.1.0] - 2026-03-13
+
+### Added
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,159 @@
+# lex-exec: Sandboxed Shell Execution for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-core/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Legion Extension that provides sandboxed shell execution within a LegionIO cluster. Runs shell commands, git operations, and bundler workflows with allowlist enforcement and a thread-safe in-memory audit log. Used by agentic swarm pipelines (e.g., `lex-swarm-github`) to validate and publish generated extensions.
+
+**GitHub**: https://github.com/LegionIO/lex-exec
+**License**: Apache-2.0
+**Version**: 0.1.1
+
+## Architecture
+
+```
+Legion::Extensions::Exec
+├── Runners/
+│   ├── Shell     # execute, audit — allowlist + blocked pattern enforcement, Open3 subprocess
+│   ├── Git       # init, add, commit, push, status, create_repo — git + gh CLI wrappers
+│   └── Bundler   # install, exec_rspec, exec_rubocop — structured output parsing
+├── Helpers/
+│   ├── Sandbox      # allowlist check, blocked pattern check
+│   ├── AuditLog     # thread-safe ring buffer (1000 entries max)
+│   ├── ResultParser # parses RSpec and RuboCop stdout into structured hashes
+│   └── Constants    # ALLOWED_COMMANDS array, BLOCKED_PATTERNS array
+└── Client           # includes Shell + Git + Bundler; stores base_path
+```
+
+No explicit actors directory. The framework auto-generates subscription actors for each runner.
+
+## Gem Info
+
+| Field | Value |
+|-------|-------|
+| Gem name | `lex-exec` |
+| Module | `Legion::Extensions::Exec` |
+| Version | `0.1.1` |
+| Ruby | `>= 3.4` |
+| Runtime deps | `open3`, `timeout` (stdlib only) |
+| License | Apache-2.0 |
+
+## File Structure
+
+```
+lex-exec/
+├── lex-exec.gemspec
+├── Gemfile
+├── lib/
+│   └── legion/
+│       └── extensions/
+│           ├── exec.rb                        # Entry point; requires all helpers/runners/client
+│           └── exec/
+│               ├── version.rb
+│               ├── client.rb                  # Client class; includes Shell + Git + Bundler
+│               ├── helpers/
+│               │   ├── sandbox.rb             # Allowlist + blocked pattern enforcement
+│               │   ├── audit_log.rb           # Thread-safe ring buffer (1000 entries)
+│               │   ├── result_parser.rb       # Parses RSpec/RuboCop stdout into structured hashes
+│               │   └── constants.rb           # ALLOWED_COMMANDS and BLOCKED_PATTERNS
+│               └── runners/
+│                   ├── shell.rb               # execute, audit
+│                   ├── git.rb                 # init, add, commit, push, status, create_repo
+│                   └── bundler.rb             # install, exec_rspec, exec_rubocop
+└── spec/
+```
+
+## Security Model
+
+### Allowlisted Commands
+
+Only the following base commands are permitted:
+
+```
+bundle  git  gh  ruby  rspec  rubocop
+ls  cat  mkdir  cp  mv  rm  touch  echo  wc  head  tail
+```
+
+### Blocked Patterns
+
+Always rejected regardless of allowlist:
+- `rm -rf /` — root deletion
+- `rm -rf ~` — home deletion
+- `rm -rf ..` — parent directory deletion
+- `sudo` — privilege escalation
+- `chmod 777` — world-writable permissions
+- `curl | sh` — pipe-to-shell download execution
+- Redirects to `/etc` or `/usr`
+
+### Limits
+
+| Parameter | Default | Maximum |
+|-----------|---------|---------|
+| Timeout | 120,000 ms | 600,000 ms (10 min) |
+| Output size (stdout + stderr) | — | 1,048,576 bytes (1 MB, truncated with flag) |
+| Audit log entries | — | 1,000 (ring buffer, oldest evicted) |
+
+## Runner Details
+
+### Shell (`Runners::Shell`)
+
+`extend self` — all methods callable on the module directly.
+
+**`execute(command:, cwd: nil, timeout: 120_000, **)`**
+- Validates command against allowlist and blocked patterns
+- Runs with `Open3.capture3` under a `Timeout::timeout` guard
+- Returns `{ success:, stdout:, stderr:, exit_code:, duration_ms:, truncated: }`
+- On failure: `{ success: false, error: :blocked/:timeout/:exception }`
+
+**`audit(limit: 100, **)`**
+- Returns entries from the ring buffer
+- Returns `{ success: true, entries: [], stats: { total:, success:, failure:, avg_duration_ms: } }`
+
+### Git (`Runners::Git`)
+
+`extend self`.
+
+| Method | Notes |
+|--------|-------|
+| `init(path:)` | `git init` |
+| `add(path:, files:)` | `git add` with string or array |
+| `commit(path:, message:)` | `git commit -m` |
+| `push(path:, remote: 'origin', branch: 'main', set_upstream: false)` | `-u` flag when `set_upstream: true` |
+| `status(path:)` | Parses `--porcelain` output into structured form |
+| `create_repo(name:, org:, description: '', public: true)` | `gh repo create --clone`; defaults branch to `main` |
+
+### Bundler (`Runners::Bundler`)
+
+`extend self`.
+
+| Method | Notes |
+|--------|-------|
+| `install(path:)` | 5 min timeout |
+| `exec_rspec(path:, format: 'progress')` | `result[:parsed]` => `{ examples:, failures:, pending:, passed: }` |
+| `exec_rubocop(path:, autocorrect: false)` | `result[:parsed]` => `{ offenses:, files_inspected: }` |
+
+## Client
+
+`Client.new(base_path: '/path/to/project')` stores `@base_path`. All runner methods delegate to the corresponding `extend self` modules with `path: @base_path`.
+
+## Integration Points
+
+- **`lex-codegen`**: Natural companion. Codegen produces the file tree; exec runs `bundle install`, `bundle exec rspec`, `bundle exec rubocop`, then commits and pushes.
+- **`lex-swarm-github`**: Swarm pipeline calls exec to validate and publish generated extensions.
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec     # 127 examples, 0 failures
+bundle exec rubocop   # 0 offenses
+```
+
+Specs mock `Open3.capture3` and `Timeout::timeout` — no real shell commands execute in tests.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+  gem 'simplecov'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Esity
+
+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,204 @@
+# lex-exec
+
+Sandboxed shell execution extension for LegionIO. Runs shell commands, git operations, and bundler workflows with allowlist enforcement and an in-memory audit log. Used by agentic swarm pipelines (e.g., `lex-swarm-github`) to validate and publish generated extensions.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'lex-exec'
+```
+
+Or install directly:
+
+```bash
+gem install lex-exec
+```
+
+## Overview
+
+`lex-exec` provides three runners:
+
+- **Shell** - Execute arbitrary shell commands against an allowlist
+- **Git** - Common git operations (init, add, commit, push, status, create_repo)
+- **Bundler** - Run `bundle install`, `rspec`, and `rubocop` with structured output parsing
+
+All shell execution goes through a `Sandbox` that checks the base command against an allowlist and rejects commands matching blocked patterns. Every execution is recorded in a thread-safe in-memory `AuditLog`.
+
+## Allowlisted Commands
+
+Only the following base commands are permitted:
+
+```
+bundle  git  gh  ruby  rspec  rubocop
+ls  cat  mkdir  cp  mv  rm  touch  echo  wc  head  tail
+```
+
+Commands not in this list are rejected before execution with `success: false, error: :blocked`.
+
+## Blocked Patterns
+
+The following patterns are always rejected regardless of allowlist membership:
+
+- `rm -rf /` (root deletion)
+- `rm -rf ~` (home deletion)
+- `rm -rf ..` (parent directory deletion)
+- `sudo` (privilege escalation)
+- `chmod 777` (world-writable permissions)
+- `curl | sh` (pipe-to-shell download execution)
+- Redirects to `/etc` or `/usr`
+
+## Limits
+
+| Parameter | Default | Maximum |
+|-----------|---------|---------|
+| Timeout | 120,000 ms | 600,000 ms (10 min) |
+| Output size (stdout/stderr) | — | 1,048,576 bytes (1 MB) |
+| Audit log entries | — | 1,000 (ring buffer) |
+
+Output exceeding 1 MB is truncated; `truncated: true` is set in the result and recorded in the audit log.
+
+## Usage
+
+### Direct runner calls
+
+```ruby
+# Shell runner
+result = Legion::Extensions::Exec::Runners::Shell.execute(
+  command: 'bundle exec rspec',
+  cwd:     '/path/to/project',
+  timeout: 120_000
+)
+# => { success: true, stdout: "...", stderr: "...", exit_code: 0, duration_ms: 1234, truncated: false }
+
+# Retrieve audit log
+audit = Legion::Extensions::Exec::Runners::Shell.audit(limit: 50)
+# => { success: true, entries: [...], stats: { total:, success:, failure:, avg_duration_ms: } }
+```
+
+### Client interface
+
+`Legion::Extensions::Exec::Client` provides a unified interface delegating to all three runners:
+
+```ruby
+client = Legion::Extensions::Exec::Client.new(base_path: '/path/to/project')
+
+# Shell
+client.execute(command: 'ls -la')
+client.audit(limit: 25)
+
+# Git
+client.init
+client.add(files: ['lib/foo.rb', 'spec/foo_spec.rb'])
+client.commit(message: 'add foo runner')
+client.push(remote: 'origin', branch: 'main', set_upstream: true)
+client.status
+client.create_repo(name: 'lex-foo', org: 'LegionIO', description: 'foo extension', public: true)
+
+# Bundler
+client.install
+client.exec_rspec(format: 'progress')
+client.exec_rubocop(autocorrect: false)
+```
+
+### Git runner
+
+```ruby
+# Initialize a new repo
+Legion::Extensions::Exec::Runners::Git.init(path: '/path/to/dir')
+
+# Stage files
+Legion::Extensions::Exec::Runners::Git.add(path: '/path/to/dir', files: '.')
+Legion::Extensions::Exec::Runners::Git.add(path: '/path/to/dir', files: ['file1.rb', 'file2.rb'])
+
+# Commit
+Legion::Extensions::Exec::Runners::Git.commit(path: '/path/to/dir', message: 'initial commit')
+
+# Push (set_upstream: true adds -u flag)
+Legion::Extensions::Exec::Runners::Git.push(path: '/path/to/dir', remote: 'origin', branch: 'main', set_upstream: true)
+
+# Status (parses --porcelain output into structured form)
+Legion::Extensions::Exec::Runners::Git.status(path: '/path/to/dir')
+
+# Create GitHub repo via gh CLI
+Legion::Extensions::Exec::Runners::Git.create_repo(
+  name:        'lex-myext',
+  org:         'LegionIO',
+  description: 'my extension',
+  public:      true
+)
+```
+
+### Bundler runner
+
+```ruby
+# Install dependencies (5 min timeout)
+Legion::Extensions::Exec::Runners::Bundler.install(path: '/path/to/project')
+
+# Run RSpec with parsed output
+result = Legion::Extensions::Exec::Runners::Bundler.exec_rspec(path: '/path/to/project', format: 'progress')
+# result[:parsed] => { examples:, failures:, pending:, passed: }
+
+# Run RuboCop with parsed output
+result = Legion::Extensions::Exec::Runners::Bundler.exec_rubocop(path: '/path/to/project')
+# result[:parsed] => { offenses:, files_inspected: }
+
+# Run RuboCop with autocorrect
+Legion::Extensions::Exec::Runners::Bundler.exec_rubocop(path: '/path/to/project', autocorrect: true)
+```
+
+## Return Value Shape
+
+All runners return a hash with at minimum:
+
+```ruby
+{
+  success:     true | false,
+  stdout:      "...",          # present on success
+  stderr:      "...",          # present on success
+  exit_code:   0,              # present on success
+  duration_ms: 123,            # present on success
+  truncated:   false           # true if stdout exceeded 1 MB
+}
+```
+
+On failure:
+
+```ruby
+{ success: false, error: :blocked, reason: "command 'sudo' is not in the allowlist" }
+{ success: false, error: :timeout, timeout_ms: 120_000 }
+{ success: false, error: "invalid argument message" }
+```
+
+## Agentic Pipeline Integration
+
+`lex-exec` is designed to work alongside `lex-codegen` in the agentic swarm pipeline:
+
+```
+lex-codegen (scaffold_extension)    # generates file tree from ERB templates
+      |
+      v
+lex-exec (Bundler.install)          # installs gem dependencies
+      |
+      v
+lex-exec (Bundler.exec_rspec)       # runs test suite, returns pass/fail counts
+      |
+      v
+lex-exec (Bundler.exec_rubocop)     # lints code, returns offense count
+      |
+      v
+lex-exec (Git.commit + Git.push)    # commits and pushes validated extension
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+Apache-2.0

data/lex-exec.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/exec/version'
+
+Gem::Specification.new do |spec|
+  spec.name                  = 'lex-exec'
+  spec.version               = Legion::Extensions::Exec::VERSION
+  spec.authors               = ['Esity']
+  spec.email                 = ['matthewdiverson@gmail.com']
+
+  spec.summary               = 'LEX::Exec'
+  spec.description           = 'Safe sandboxed shell execution for LegionIO'
+  spec.homepage              = 'https://github.com/LegionIO/lex-exec'
+  spec.license               = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-exec'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-exec'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-exec'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-exec/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.require_paths = ['lib']
+end

data/lib/legion/extensions/exec/client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      class Client
+        def initialize(base_path: Dir.pwd)
+          @base_path = base_path
+        end
+
+        # Shell delegation
+        def execute(command:, cwd: @base_path, **)
+          Runners::Shell.execute(command: command, cwd: cwd, **)
+        end
+
+        def audit(**)
+          Runners::Shell.audit(**)
+        end
+
+        # Git delegation
+        def init(path: @base_path, **)
+          Runners::Git.init(path: path)
+        end
+
+        def add(path: @base_path, **)
+          Runners::Git.add(path: path, **)
+        end
+
+        def commit(path: @base_path, **)
+          Runners::Git.commit(path: path, **)
+        end
+
+        def push(path: @base_path, **)
+          Runners::Git.push(path: path, **)
+        end
+
+        def status(path: @base_path, **)
+          Runners::Git.status(path: path)
+        end
+
+        def create_repo(**)
+          Runners::Git.create_repo(**)
+        end
+
+        # Bundler delegation
+        def install(path: @base_path, **)
+          Runners::Bundler.install(path: path)
+        end
+
+        def exec_rspec(path: @base_path, **)
+          Runners::Bundler.exec_rspec(path: path, **)
+        end
+
+        def exec_rubocop(path: @base_path, **)
+          Runners::Bundler.exec_rubocop(path: path, **)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/helpers/audit_log.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      module Helpers
+        class AuditLog
+          MAX_ENTRIES = 1000
+
+          def initialize
+            @entries = []
+            @mutex   = Mutex.new
+          end
+
+          def record(command:, cwd:, exit_code:, duration_ms:, truncated: false)
+            entry = {
+              command:     command,
+              cwd:         cwd,
+              exit_code:   exit_code,
+              duration_ms: duration_ms,
+              truncated:   truncated,
+              executed_at: Time.now.utc.iso8601
+            }
+
+            @mutex.synchronize do
+              @entries << entry
+              @entries.shift while @entries.size > MAX_ENTRIES
+            end
+          end
+
+          def entries(limit: 50)
+            @mutex.synchronize { @entries.last(limit) }
+          end
+
+          def stats
+            @mutex.synchronize do
+              total    = @entries.size
+              success  = @entries.count { |e| e[:exit_code].zero? }
+              failure  = total - success
+              avg_dur  = total.zero? ? 0 : (@entries.sum { |e| e[:duration_ms] } / total.to_f).round(2)
+
+              { total: total, success: success, failure: failure, avg_duration_ms: avg_dur }
+            end
+          end
+
+          def clear
+            @mutex.synchronize { @entries.clear }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/helpers/checkpoint.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Legion
+  module Extensions
+    module Exec
+      module Helpers
+        module Checkpoint
+          class << self
+            def save(worktree_path:, label:, task_id:)
+              Dir.chdir(worktree_path) do
+                Open3.capture3('git', 'add', '-A')
+
+                tree_sha, _err, tree_status = Open3.capture3('git', 'write-tree')
+                return { success: false, reason: :write_tree_failed } unless tree_status.success?
+
+                tree_sha = tree_sha.strip
+                commit_sha, _err, commit_status = Open3.capture3(
+                  'git', 'commit-tree', tree_sha, '-m', "checkpoint: #{label}"
+                )
+                return { success: false, reason: :commit_tree_failed } unless commit_status.success?
+
+                commit_sha = commit_sha.strip
+                ref = "refs/checkpoints/#{task_id}/#{label}"
+                _out, _err, ref_status = Open3.capture3('git', 'update-ref', ref, commit_sha)
+                return { success: false, reason: :update_ref_failed } unless ref_status.success?
+
+                Open3.capture3('git', 'reset', 'HEAD')
+                { success: true, ref: ref, commit: commit_sha }
+              end
+            end
+
+            def restore(worktree_path:, label:, task_id:)
+              ref = "refs/checkpoints/#{task_id}/#{label}"
+              Dir.chdir(worktree_path) do
+                _stdout, stderr, status = Open3.capture3('git', 'checkout', ref, '--', '.')
+                status.success? ? { success: true, ref: ref } : { success: false, message: stderr.strip }
+              end
+            end
+
+            def list_checkpoints(task_id:)
+              pattern = "refs/checkpoints/#{task_id}/"
+              stdout, = Open3.capture3('git', 'for-each-ref', '--format=%(refname) %(creatordate:iso8601)', pattern)
+              checkpoints = stdout.strip.split("\n").filter_map do |line|
+                next if line.strip.empty?
+
+                parts = line.split(' ', 2)
+                label = parts[0].sub(pattern, '')
+                { label: label, created_at: parts[1] }
+              end
+              { success: true, checkpoints: checkpoints }
+            end
+
+            def prune(task_id:)
+              pattern = "refs/checkpoints/#{task_id}/"
+              stdout, = Open3.capture3('git', 'for-each-ref', '--format=%(refname)', pattern)
+              refs = stdout.strip.split("\n").reject(&:empty?)
+              refs.each { |ref| Open3.capture3('git', 'update-ref', '-d', ref) }
+              { success: true, pruned: refs.size }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/helpers/constants.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      module Helpers
+        module Constants
+          DEFAULT_TIMEOUT   = 120_000 # 120 seconds in ms
+          MAX_TIMEOUT       = 600_000 # 10 minutes in ms
+          MAX_OUTPUT_BYTES  = 1_048_576 # 1 MB
+
+          ALLOWED_COMMANDS = %w[
+            bundle git gh ruby rspec rubocop ls cat mkdir cp mv rm touch echo wc head tail
+          ].freeze
+
+          BLOCKED_PATTERNS = [
+            %r{rm\s+-rf\s+/},
+            /rm\s+-rf\s+~/,
+            /rm\s+-rf\s+\.\./,
+            /sudo/,
+            /chmod\s+777/,
+            /curl.*\|.*sh/,
+            %r{>\s*/etc},
+            %r{>\s*/usr}
+          ].freeze
+
+          AUDIT_FIELDS = %i[command cwd exit_code duration_ms executed_at truncated].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/helpers/result_parser.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      module Helpers
+        module ResultParser
+          module_function
+
+          def parse_rspec(output)
+            examples = 0
+            failures = 0
+            pending  = 0
+
+            if (match = output.match(/(\d+)\s+examples?,\s+(\d+)\s+failures?/))
+              examples = match[1].to_i
+              failures = match[2].to_i
+            end
+
+            if (match = output.match(/(\d+)\s+pending/))
+              pending = match[1].to_i
+            end
+
+            { examples: examples, failures: failures, pending: pending, passed: failures.zero? }
+          end
+
+          def parse_rubocop(output)
+            files    = 0
+            offenses = 0
+
+            if (match = output.match(/(\d+)\s+files?\s+inspected,\s+(\d+)\s+offenses?\s+detected/))
+              files    = match[1].to_i
+              offenses = match[2].to_i
+            end
+
+            { files: files, offenses: offenses, clean: offenses.zero? }
+          end
+
+          def parse_git_status(output)
+            modified   = []
+            untracked  = []
+            deleted    = []
+
+            output.each_line do |line|
+              code = line[0..1].strip
+              file = line[3..].strip
+
+              case code
+              when 'M', 'MM', 'AM'
+                modified << file
+              when '??'
+                untracked << file
+              when 'D', 'MD'
+                deleted << file
+              end
+            end
+
+            {
+              clean:     modified.empty? && untracked.empty? && deleted.empty?,
+              modified:  modified,
+              untracked: untracked,
+              deleted:   deleted
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/helpers/sandbox.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      module Helpers
+        class Sandbox
+          def initialize(allowed_commands: Helpers::Constants::ALLOWED_COMMANDS,
+                         blocked_patterns: Helpers::Constants::BLOCKED_PATTERNS)
+            @allowed_commands = allowed_commands
+            @blocked_patterns = blocked_patterns
+          end
+
+          def allowed?(command)
+            base = base_command(command)
+
+            return { allowed: false, reason: "command '#{base}' is not in the allowlist" } unless @allowed_commands.include?(base)
+
+            @blocked_patterns.each do |pattern|
+              return { allowed: false, reason: "command matches blocked pattern: #{pattern.source}" } if pattern.match?(command)
+            end
+
+            { allowed: true, reason: nil }
+          end
+
+          def sanitize(command)
+            command.gsub(/[`$()]/, '')
+          end
+
+          private
+
+          def base_command(command)
+            command.strip.split(/\s+/).first.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/helpers/worktree.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'fileutils'
+
+module Legion
+  module Extensions
+    module Exec
+      module Helpers
+        module Worktree
+          class << self
+            def create(task_id:, branch: nil, base_ref: 'HEAD')
+              branch ||= "legion/#{task_id}"
+              path = worktree_path(task_id)
+              return { success: false, reason: :already_exists } if Dir.exist?(path)
+
+              FileUtils.mkdir_p(File.dirname(path))
+              _stdout, stderr, status = Open3.capture3('git', 'worktree', 'add', path, '-b', branch, base_ref)
+              if status.success?
+                { success: true, path: path, branch: branch }
+              else
+                { success: false, reason: :git_error, message: stderr.strip }
+              end
+            end
+
+            def remove(task_id:)
+              path = worktree_path(task_id)
+              return { success: false, reason: :not_found } unless Dir.exist?(path)
+
+              _stdout, stderr, status = Open3.capture3('git', 'worktree', 'remove', path, '--force')
+              if status.success?
+                { success: true }
+              else
+                { success: false, reason: :git_error, message: stderr.strip }
+              end
+            end
+
+            def list
+              stdout, _stderr, _status = Open3.capture3('git', 'worktree', 'list', '--porcelain')
+              worktrees = parse_worktree_list(stdout)
+              { success: true, worktrees: worktrees }
+            end
+
+            def worktree_path(task_id)
+              base = Legion::Settings.dig(:worktree, :base_dir) if defined?(Legion::Settings)
+              File.join(base || File.join(Dir.pwd, '.legion-worktrees'), task_id.to_s)
+            end
+
+            private
+
+            def parse_worktree_list(output)
+              output.split("\n\n").filter_map do |block|
+                lines = block.strip.split("\n")
+                next if lines.empty?
+
+                path = lines.find { |l| l.start_with?('worktree ') }&.sub('worktree ', '')
+                branch = lines.find { |l| l.start_with?('branch ') }&.sub('branch ', '')
+                { path: path, branch: branch } if path
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/runners/bundler.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      module Runners
+        module Bundler
+          module_function
+
+          def install(path:, **)
+            Runners::Shell.execute(command: 'bundle install', cwd: path, timeout: 300_000)
+          end
+
+          def exec_rspec(path:, format: 'progress', **)
+            result = Runners::Shell.execute(
+              command: "bundle exec rspec --format #{format}",
+              cwd:     path,
+              timeout: 300_000
+            )
+            return result unless result[:stdout] || result[:stderr]
+
+            raw     = result[:stdout] || result[:stderr] || ''
+            parsed  = Helpers::ResultParser.parse_rspec(raw)
+            result.merge(parsed: parsed)
+          end
+
+          def exec_rubocop(path:, autocorrect: false, **)
+            cmd    = autocorrect ? 'bundle exec rubocop -A' : 'bundle exec rubocop'
+            result = Runners::Shell.execute(command: cmd, cwd: path, timeout: 120_000)
+            return result unless result[:stdout]
+
+            parsed = Helpers::ResultParser.parse_rubocop(result[:stdout] || '')
+            result.merge(parsed: parsed)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/runners/git.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      module Runners
+        module Git
+          module_function
+
+          def init(path:, **)
+            Runners::Shell.execute(command: 'git init', cwd: path)
+          end
+
+          def add(path:, files: '.', **)
+            cmd = files == '.' ? 'git add -A' : "git add #{Array(files).join(' ')}"
+            Runners::Shell.execute(command: cmd, cwd: path)
+          end
+
+          def commit(path:, message:, **)
+            safe_msg = message.gsub("'", "\\'")
+            Runners::Shell.execute(command: "git commit -m '#{safe_msg}'", cwd: path)
+          end
+
+          def push(path:, remote: 'origin', branch: 'main', set_upstream: false, **)
+            cmd = set_upstream ? "git push -u #{remote} #{branch}" : 'git push'
+            Runners::Shell.execute(command: cmd, cwd: path)
+          end
+
+          def status(path:, **)
+            result = Runners::Shell.execute(command: 'git status --porcelain', cwd: path)
+            return result unless result[:success]
+
+            parsed = Helpers::ResultParser.parse_git_status(result[:stdout] || '')
+            result.merge(parsed: parsed)
+          end
+
+          def create_repo(name:, org: 'LegionIO', description: '', public: true, **)
+            visibility = public ? '--public' : '--private'
+            Runners::Shell.execute(
+              command: "gh repo create #{org}/#{name} #{visibility} --description '#{description}' --clone",
+              cwd:     Dir.pwd
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/runners/shell.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+
+module Legion
+  module Extensions
+    module Exec
+      module Runners
+        module Shell
+          extend self
+
+          def execute(command:, cwd: Dir.pwd, timeout: Helpers::Constants::DEFAULT_TIMEOUT, env: {}, **)
+            check = default_sandbox.allowed?(command)
+            return { success: false, error: :blocked, reason: check[:reason] } unless check[:allowed]
+
+            start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            timeout_secs = [timeout, Helpers::Constants::MAX_TIMEOUT].min / 1000.0
+
+            begin
+              stdout, stderr, status = Timeout.timeout(timeout_secs) do
+                Open3.capture3(env, command, chdir: cwd)
+              end
+            rescue Timeout::Error
+              return { success: false, error: :timeout, timeout_ms: timeout }
+            rescue ArgumentError => e
+              return { success: false, error: e.message }
+            end
+
+            duration_ms = ((::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+            exit_code   = status.exitstatus.to_i
+            truncated   = false
+
+            if stdout.bytesize > Helpers::Constants::MAX_OUTPUT_BYTES
+              stdout    = stdout.byteslice(0, Helpers::Constants::MAX_OUTPUT_BYTES)
+              truncated = true
+            end
+
+            stderr = stderr.byteslice(0, Helpers::Constants::MAX_OUTPUT_BYTES) if stderr.bytesize > Helpers::Constants::MAX_OUTPUT_BYTES
+
+            audit_log.record(command: command, cwd: cwd, exit_code: exit_code,
+                             duration_ms: duration_ms, truncated: truncated)
+
+            Legion::Logging.debug("[lex-exec] exit=#{exit_code} duration=#{duration_ms}ms cmd=#{command}")
+
+            {
+              success:     exit_code.zero?,
+              stdout:      stdout,
+              stderr:      stderr,
+              exit_code:   exit_code,
+              duration_ms: duration_ms,
+              truncated:   truncated
+            }
+          end
+
+          def audit(limit: 50, **)
+            { success: true, entries: audit_log.entries(limit: limit), stats: audit_log.stats }
+          end
+
+          private
+
+          def default_sandbox
+            @default_sandbox ||= Helpers::Sandbox.new
+          end
+
+          def audit_log
+            @audit_log ||= Helpers::AuditLog.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/exec/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Exec
+      VERSION = '0.1.3'
+    end
+  end
+end

data/lib/legion/extensions/exec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'exec/version'
+require_relative 'exec/helpers/constants'
+require_relative 'exec/helpers/sandbox'
+require_relative 'exec/helpers/result_parser'
+require_relative 'exec/helpers/audit_log'
+require_relative 'exec/helpers/checkpoint'
+require_relative 'exec/helpers/worktree'
+require_relative 'exec/runners/shell'
+require_relative 'exec/runners/git'
+require_relative 'exec/runners/bundler'
+require_relative 'exec/client'
+
+module Legion
+  module Extensions
+    module Exec
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-exec
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Esity
@@ -15,7 +15,29 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- lex-exec.gemspec
+- lib/legion/extensions/exec.rb
+- lib/legion/extensions/exec/client.rb
+- lib/legion/extensions/exec/helpers/audit_log.rb
+- lib/legion/extensions/exec/helpers/checkpoint.rb
+- lib/legion/extensions/exec/helpers/constants.rb
+- lib/legion/extensions/exec/helpers/result_parser.rb
+- lib/legion/extensions/exec/helpers/sandbox.rb
+- lib/legion/extensions/exec/helpers/worktree.rb
+- lib/legion/extensions/exec/runners/bundler.rb
+- lib/legion/extensions/exec/runners/git.rb
+- lib/legion/extensions/exec/runners/shell.rb
+- lib/legion/extensions/exec/version.rb
 homepage: https://github.com/LegionIO/lex-exec
 licenses:
 - MIT