srgn CLI

Overview

srgn

Workflow Decision Tree

1. Classify the request.
   • Search only: no content changes expected.
   • Transform in stream: stdin/stdout pipeline usage.
   • Transform files: in-place updates over globs.
2. Identify scope strategy.
   • Regex scope only.
   • Language scope only.
   • Combined language + regex scope.
   • Custom tree-sitter query scope.
3. Identify action strategy.
   • Replacement (positional replacement argument after

     --

     ).
   • Composable actions (

     --upper

     ,

     --lower

     ,

     --titlecase

     ,

     --normalize

     ,

     --symbols

     ,

     --german

     ).
   • Standalone actions (

     -d

     ,

     -s

     ).
4. Apply safety controls.
   • Prefer

     --dry-run

     for file operations.
   • Keep globs quoted.
   • Add

     --fail-no-files

     when missing files should fail CI.
5. Choose output mode.
   • Human-readable (default tty).
   • Machine-readable (

     --stdout-detection force-pipe

     ).
6. Validate behavior.
   • Confirm expected match count.
   • Confirm no out-of-scope edits.
   • Re-run with stricter scope if needed.

Safety Protocol

1. Default to non-destructive behavior first.
   • Prefer stdin-based or search-mode examples before in-place rewrites.
2. For file edits, require preview path.
   • Use

     --dry-run

     first.
   • Then run the same command without

     --dry-run

     only after confirmation.
3. Protect shell parsing boundaries.
   • Quote regex.
   • Quote globs:

     --glob '**/*.py'

     .
   • Use

     --

     before replacement values.
4. Use the narrowest scope that solves the task.
   • Prefer language scope + anchored regex over broad regex-only replacement.
5. Treat

   -d

   and

   -s

   as high-risk operations.
   • Always provide explicit scope for them.

Command Construction Template

srgn [LANGUAGE_SCOPE_FLAGS...] [GLOBAL_FLAGS...] [ACTION_FLAGS...] [SCOPE_REGEX] -- [REPLACEMENT]

1. Scope first.
   • Example:

     --python 'imports'

2. Regex filter second.
   • Example:

     '^old_pkg'

3. Action third.
   • Replacement:

     -- 'new_pkg'

   • Or composable flag:

     --upper

4. File mode flags fourth (if needed).

   • --glob '**/*.py' --dry-run

5. CI behavior last.

   • --fail-any

     or

     --fail-none

High-Value Task Recipes

1. Rename module imports in Python only:

srgn --python 'imports' '^old_pkg' --glob '**/*.py' --dry-run -- 'new_pkg'

1. Convert

   print

   calls to logging in Python call-sites only:

srgn --python 'function-calls' '^print$' --glob '**/*.py' --dry-run -- 'logging.info'

1. Rename Rust

   use

   prefixes without touching strings/comments:

srgn --rust 'uses' '^good_company' --glob '**/*.rs' --dry-run -- 'better_company'

1. Remove C# comments only:

srgn --csharp 'comments' -d '.*'

1. Search for Rust

   unsafe

   language keyword usage only:

srgn --rust 'unsafe'

1. Fail CI if undesirable pattern appears in Python docstrings:

srgn --python 'doc-strings' --fail-any 'param.+type'

1. Force machine-readable output for downstream parsers:

srgn --python 'strings' --stdout-detection force-pipe '(foo|bar)'

1. Preview multi-file changes with deterministic ordering:

srgn --typescript 'imports' '^legacy-lib' --glob 'src/**/*.ts' --sorted --dry-run -- 'modern-lib'

references/cli-cookbook.md

Failure and Debug Playbook

1. No matches when matches are expected.
   • Verify language scope and prepared query name.
   • Remove regex temporarily to test scope alone.
   • Add

     --stdout-detection force-pipe

     to inspect exact matched columns.
2. Too many matches.
   • Anchor regex (

     ^...$

     ) where possible.
   • Narrow from generic language scope to a specific prepared query.
3. Wrong files targeted.
   • Confirm

     --glob

     pattern and shell quoting.
   • Add

     --fail-no-files

     in CI to catch empty globs.
4. Unclear behavior across multiple language scopes.
   • Default is intersection (left-to-right narrowing).
   • Use

     -j

     for OR behavior.
5. Special characters misinterpreted as regex.
   • Use

     --literal-string

     when literal matching is intended.

Reference Loading Guide

1. references/cli-cookbook.md

   • Load for routine command construction and practical recipes.

2. references/language-scopes.md

   • Load for prepared query selection by language.

3. references/advanced-patterns.md

   • Load for custom queries, capture substitutions, join semantics, and CI failure modes.

4. references/deepwiki-recursive-notes.md

   • Load for complete DeepWiki-derived background and architecture context.

Intent-to-Command Map

1. "Rename imports safely"
   • Use language import scope + anchored regex +

     --glob ... --dry-run

     .
2. "Update function calls only"
   • Use language call-site scope (for example

     --python 'function-calls'

     ) + exact name regex.
3. "Only comments/docstrings"
   • Use prepared comment/docstring scopes, add

     -j

     only when OR semantics are required.
4. "CI should fail if pattern appears"
   • Use scoped search +

     --fail-any

     .
5. "CI should fail if required pattern is missing"
   • Use scoped search +

     --fail-none

     .
6. "I need parseable output"
   • Use

     --stdout-detection force-pipe

     .
7. "Regex escaping is painful"
   • Use

     --literal-string

     and explicit replacement via

     --

     .

Execution Checklist

1. Scope is minimal and syntax-aware where possible.
2. Replacement argument is after

   --

   (if replacement is used).
3. Globs are quoted.

4. --dry-run

   is present for file edits unless user requested direct apply.
5. Join semantics are explicit when multiple language scopes are used (

   -j

   vs default intersect).
6. Failure flags align with user intent (

   --fail-any

   ,

   --fail-none

   ,

   --fail-no-files

   ).
7. Output mode is explicit if user needs machine parsing.