ask-tools-shell 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40e217bcf42a1f1cdf4b3bf6d256e06aa21ee4e9c946706a1728dc8bf049e6a0
-  data.tar.gz: cb157c2d84e1c162de9cab25394dec75ffdf65276e55a70537acc145424a7c1f
+  metadata.gz: 57dd21c05244ce8dfcdc2b9c631ed37983b0d87071421906c7a38b090a36d237
+  data.tar.gz: 786e6bb78c5f98840d45554d77c826ddec8c94320fba1696425833e865bfef6e
 SHA512:
-  metadata.gz: 9b204fd0304eb672ad90c8359bafe27454441019079a64a38a73026f8fc3b0003098cb9df034827feb19324490c82f88d67b9642d521a3a7aad0769cb0cab9c7
-  data.tar.gz: 9150cd2ccab75a75dfec81125b6ab6c8308ae2853a07e4d158e3244a231777acbd2f03895deacf53c910f2229f06005c70a032253ee6c14a02c2d7381e9e1149
+  metadata.gz: cc2b723b0e12766e682ad46cebe01b60cd35fbc8df1fbece1c165f03f05bdfd3b534745cb57af78dac6bf550130a6cc21431f67f31d640ce025cfef7ec91b300
+  data.tar.gz: 7f5bf812384a63539c90b153d3bb1e5bfc30014634f357ce49bbf4f8860fbb423ac0dda9e813da12f50e0a0d6c3614e7b8a95dfaee95c738674bfcd53a3e4ec3

data/lib/ask/skills/shell.patterns/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: shell.patterns
+description: Common shell tool composition patterns for code analysis, searching, and file manipulation
+---
+
+Use this skill when you need to search, analyze, or manipulate a codebase using
+shell tools. These patterns show you the most effective way to combine tools
+for common tasks.
+
+## Pattern 1: Find and Search with Glob + Grep
+
+The most powerful pattern for code analysis is combining Glob and Grep.
+
+**Find files of a type, then search their contents:**
+
+```ruby
+# Step 1: Find relevant files
+result = Glob.new.call(pattern: "**/*.rb", path: "/path/to/project")
+
+# Step 2: Search for a pattern in those files
+Grep.new.call(pattern: "class.*API", path: "/path/to/project", include: "*.rb")
+```
+
+**Search first to narrow, then read specific files:**
+
+```ruby
+# Step 1: Find where a method is used
+Grep.new.call(pattern: "def process_payment", path: "/project")
+
+# Step 2: Read the specific files found
+Read.new.call(path: "/project/app/services/payment_processor.rb")
+```
+
+## Pattern 2: Read Files with Offset/Limit
+
+When reading large files, use offset and limit to navigate:
+
+```ruby
+# Read the first 50 lines
+Read.new.call(path: "large_file.rb", limit: 50)
+
+# Then read from where you left off
+Read.new.call(path: "large_file.rb", offset: 50, limit: 50)
+```
+
+This avoids truncation and lets you browse files in chunks.
+
+## Pattern 3: Pipe Shell Commands via Bash
+
+For complex queries that aren't a simple grep, use Bash with pipes:
+
+```ruby
+# Count lines of Ruby code
+Bash.new.call(command: "find . -name '*.rb' -exec cat {} \\; | wc -l", workdir: "/project")
+
+# Find the top 10 largest files
+Bash.new.call(command: "find . -name '*.rb' -exec wc -l {} \\; | sort -rn | head -10", workdir: "/project")
+
+# Search git history
+Bash.new.call(command: "git log --oneline --all --grep='fix' | head -20", workdir: "/project")
+```
+
+## Pattern 4: Edit with Read + Edit + Read
+
+The safe way to make changes is Read → Edit → Read:
+
+```ruby
+# Step 1: Read the file to find exact text
+Read.new.call(path: "app/models/user.rb")
+
+# Step 2: Edit with exact match (provide surrounding context for uniqueness)
+Edit.new.call(
+  path: "app/models/user.rb",
+  old_string: "has_many :posts",
+  new_string: "has_many :posts, dependent: :destroy"
+)
+
+# Step 3: Verify the change
+Read.new.call(path: "app/models/user.rb", limit: 30)
+```
+
+When a string could appear multiple times:
+```ruby
+# First verify occurrences
+Grep.new.call(pattern: "old_string", path: "/project")
+
+# Then replace all if appropriate
+Edit.new.call(path: "file.rb", old_string: "old", new_string: "new", replace_all: true)
+```
+
+## Pattern 5: Code Execution for Quick Ruby Checks
+
+Use Code for ad-hoc Ruby that doesn't need tools:
+
+```ruby
+# Check Ruby version or gem availability
+Code.new.call(code: "puts Gem::Specification.map(&:name).grep(/devise/).first")
+
+# Parse and inspect data structures
+Code.new.call(code: "require 'json'; data = JSON.parse(File.read('data.json')); puts data.keys")
+
+# Test a regex before using it in Grep
+Code.new.call(code: "puts /foo.*bar/.match?('foo_baz_bar')")
+```
+
+## Pattern 6: Write Files with Content
+
+Create or overwrite files with Write:
+
+```ruby
+# Create a new file
+Write.new.call(path: "/project/app/services/new_service.rb", content: <<~RUBY)
+  class NewService
+    def call
+      # ...
+    end
+  end
+RUBY
+```
+
+Write creates parent directories automatically — no need for mkdir -p first.
+
+## Pattern 7: Project Structure Overview
+
+Get a quick lay of the land:
+
+```ruby
+# List top-level structure
+Read.new.call(path: "/project")
+
+# Count files by type
+Bash.new.call(command: "find . -name '*.rb' | sed 's/.*\\.//' | sort | uniq -c | sort -rn", workdir: "/project")
+
+# List all models or controllers
+Glob.new.call(pattern: "app/models/**/*.rb", path: "/project")
+Glob.new.call(pattern: "app/controllers/**/*.rb", path: "/project")
+```
+
+## Pattern 8: Search with Exclusions
+
+To exclude test directories or vendor code:
+
+```ruby
+# Grep already excludes .git, node_modules, vendor, .bundle, tmp, log
+# For additional exclusions, use Bash:
+Bash.new.call(
+  command: "grep -rn 'search_term' app/ lib/ --include='*.rb' | grep -v '_spec.rb' | head -50",
+  workdir: "/project"
+)
+```
+
+## Pattern 9: Sequential File Processing
+
+When you need to apply the same pattern across multiple files:
+
+```ruby
+# Step 1: Find the files
+result = Glob.new.call(pattern: "app/views/**/*.erb", path: "/project")
+
+# Step 2: Search for the pattern you need to understand
+Grep.new.call(pattern: "data-controller", path: "/project", include: "*.erb")
+```
+
+## Efficiency Guide
+
+| Task | Best Tool | Why |
+|------|-----------|-----|
+| Find files by name pattern | Glob | Fast, sorted newest first |
+| Search file contents | Grep | Pattern-aware, excludes cruft |
+| Read small files | Read | Line numbers, truncation-safe |
+| Read large files | Read (offset/limit) | Navigate in chunks |
+| Complex shell queries | Bash | Full shell power |
+| Ad-hoc Ruby checks | Code | Direct Ruby execution |
+| Make changes | Edit | Exact string replacement |
+| Create files | Write | Mkdir-p + write in one |

data/lib/ask/tools/shell/version.rb

@@ -3,7 +3,7 @@
 module Ask
   module Tools
     module Shell
-      VERSION = "0.2.0"
+      VERSION = "0.2.1"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools-shell
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -89,6 +89,7 @@ files:
 - LICENSE
 - README.md
 - lib/ask-tools-shell.rb
+- lib/ask/skills/shell.patterns/SKILL.md
 - lib/ask/tools/shell.rb
 - lib/ask/tools/shell/bash.rb
 - lib/ask/tools/shell/code.rb