outlinedriven/odin-codex-plugin/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. --glob accepts exactly one pattern (cannot repeat).

• Glob syntax: *, ?, [...], ** only. No {a,b} brace expansion.
• For multiple files: broader glob + --dry-run, or per-file via fd (CWD only—no [path] arg):

fd -e <ext> --strip-cwd-prefix -x srgn --glob '{}' --stdin-detection force-unreadable [OPTIONS] [PATTERN]

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. --glob used multiple times.

• --glob is a single-value argument; cannot repeat.
• Broader glob + --dry-run, or per-file (CWD only—no [path] arg): fd -e <ext> --strip-cwd-prefix -x srgn --glob '{}' --stdin-detection force-unreadable [OPTIONS] [PATTERN]

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.