Copilot instructions

1---
2applyTo: "lib/**/*.rb"
3---
4 
5# Library Code Instructions
6 
7## Error Handling
8 
9- Use specific error classes: `Rex::RuntimeError`, `Rex::ConnectionError`, `Rex::TimeoutError`, `ArgumentError`
10- NEVER `raise "bare string"` — makes targeted rescue impossible
11- NEVER bare `rescue` — it discards the exception object, making debugging impossible
12- NEVER `rescue Exception` — it catches `SignalException` and `SystemExit` (hides Ctrl-C and kill signals)
13- Always: `rescue StandardError => e` or more specific
14- Propagate with context: `raise Rex::ConnectionError, "Failed to connect to #{host}: #{e.message}"`
15 
16## Documentation
17 
18- Add YARD `@param` and `@return` tags to ALL public methods
19- Link to RFC/spec when implementing binary or protocol parsers
20- Add `# frozen_string_literal: true` to new library files; use `String.new` where a mutable string is needed
21 
22## Naming
23 
24- Do NOT use `get_`/`set_` prefixes for accessor-style methods (use `def version` not `def get_version`)
25- Method parameter names must be at least 2 characters
26 
27## Patterns
28 
29- Use `Rex::Stopwatch.elapsed_time` for timing
30- Use `Rex::MIME::Message` for MIME (not hardcoded XML)
31- Use `Rex::RandomIdentifier::Generator` for random variable names (specify target language)
32- Use `RubySMB` library for SMB operations
33 
34## Testing
35 
36- ALL library changes require RSpec tests in `spec/` mirroring `lib/` structure
37- Follow [Better Specs](https://www.betterspecs.org/) conventions
38- Run: `bundle exec rspec spec/path/to/spec.rb` or `:42` for single example
39 
40## Quality
41 
42- Keep PRs focused — small fixes are easier to review
43- When overriding `cleanup`, always call `super`
44- Hash cracking implementations require test hash in `tools/dev/hash_cracker_validator.rb`
45