srgn-cli（srgn CLI 搜索）

srgn CLI

Overview

Use this skill to convert user intent into precise srgn commands with safe defaults. Focus on CLI workflows for search, transformation, scoped migrations, and lint-like checks.

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.

1. Identify scope strategy.

- Regex scope only. - Language scope only. - Combined language + regex scope. - Custom tree-sitter query scope.

1. Identify action strategy.

- Replacement (positional replacement argument after --). - Composable actions (--upper, --lower, --titlecase, --normalize, --symbols, --german). - Standalone actions (-d, -s).

1. Apply safety controls.

- Prefer --dry-run for file operations. - Keep globs quoted. - Add --fail-no-files when missing files should fail CI.

1. Choose output mode.

- Human-readable (default tty). - Machine-readable (--stdout-detection force-pipe).

1. 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.

1. For file edits, require preview path.

- Use --dry-run first. - Then run the same command without --dry-run only after confirmation.

1. Protect shell parsing boundaries.

- Quote regex. - Quote globs: --glob '**/*.py'. - Use -- before replacement values.

1. Use the narrowest scope that solves the task.

- Prefer language scope + anchored regex over broad regex-only replacement.

1. Treat -d and -s as high-risk operations.

- Always provide explicit scope for them.

Command Construction Template

Use this template when building commands:

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

Build incrementally:

1. Scope first.

- Example: --python 'imports'

1. Regex filter second.

- Example: '^old_pkg'

1. Action third.

- Replacement: -- 'new_pkg' - Or composable flag: --upper

1. File mode flags fourth (if needed).

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

1. 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'

For broader, categorized examples, load 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.

1. Too many matches.

- Anchor regex (^...$) where possible. - Narrow from generic language scope to a specific prepared query.

1. Wrong files targeted.

- Confirm --glob pattern and shell quoting. - Add --fail-no-files in CI to catch empty globs.

1. Unclear behavior across multiple language scopes.

- Default is intersection (left-to-right narrowing). - Use -j for OR behavior.

1. Special characters misinterpreted as regex.

- Use --literal-string when literal matching is intended.

Reference Loading Guide

Load reference files based on request type:

1. references/cli-cookbook.md

- Load for routine command construction and practical recipes.

1. references/language-scopes.md

- Load for prepared query selection by language.

1. references/advanced-patterns.md

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

1. references/deepwiki-recursive-notes.md

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

Intent-to-Command Map

Use this map to respond quickly:

1. "Rename imports safely"

- Use language import scope + anchored regex + --glob... --dry-run.

1. "Update function calls only"

- Use language call-site scope (for example --python 'function-calls') + exact name regex.

1. "Only comments/docstrings"

- Use prepared comment/docstring scopes, add -j only when OR semantics are required.

1. "CI should fail if pattern appears"

- Use scoped search + --fail-any.

1. "CI should fail if required pattern is missing"

- Use scoped search + --fail-none.

1. "I need parseable output"

- Use --stdout-detection force-pipe.

1. "Regex escaping is painful"

- Use --literal-string and explicit replacement via --.

Execution Checklist

Before returning a final command, verify:

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.