stack-audit

# Stack Audit Scan a codebase to identify Outfitter Stack adoption candidates and generate an audit report. ## Quick Start **Option 1: Run the scanner** (recommended for large projects) ```bash bun run plugins/outfitter-stack/skills/stack-audit/scripts/init-audit.ts [project-root] ``` Generates `.outfitter/adopt/` with: - `audit-report.md` - Scan results and scope - `plan/` - Stage-by-stage task files **Option 2: Manual scan** (smaller projects) Run the audit commands below to understand scope. ## Audit Commands ### Critical Issues - Exceptions ```bash # Count throw statements rg "throw (new |[a-zA-Z])" --type ts -c # List throw locations rg "throw (new |[a-zA-Z])" --type ts -n # Count try-catch blocks rg "(try \{|catch \()" --type ts -c ``` ### Console Usage ```bash # Count console statements rg "console\.(log|error|warn|debug|info)" --type ts -c # List console locations rg "console\.(log|error|warn|debug|info)" --type ts -n ``` ### Hardcoded Paths ```bash # Homedir usage rg "(homedir\(\)|os\.homedir)" --type ts -c # Tilde paths rg "~/\." --type ts -c # Combined path issues rg "(homedir|~\/\.)" --type ts -n ``` ### Custom Error Classes ```bash # Find custom error classes rg "class \w+Error extends Error" --type ts -n # Count usage of custom errors rg "new MyCustomError\(" --type ts -c ``` ## Generated Structure ``` .outfitter/adopt/ ├── audit-report.md # Scan results, scope, recommendations └── plan/ ├── 00-overview.md # Status dashboard, dependencies ├── 01-foundation.md # Dependencies, context, logger ├── 02-handlers.md # Handler conversions ├── 03-errors.md # Error taxonomy mappings ├── 04-paths.md # XDG path migrations ├── 05-adapters.md # CLI/MCP transport layers ├── 06-documents.md # Documentation updates └── 99-unknowns.md # Items requiring review ``` ## Migration Stages | Stage | Blocked By | Focus | |-------|------------|-------| | 1. Foundation | - | Install packages, create context/logger | | 2. Handlers | Foundation | Convert throw to Result | | 3. Errors | Handlers | Map to error taxonomy | | 4. Paths | - | XDG paths, securePath | | 5. Adapters | Handlers | CLI/MCP wrappers | | 6. Documents | All | Update docs to reflect patterns | | 99. Unknowns | - | Review anytime | ## Audit Report Fields | Field | Description | |-------|-------------| | Exceptions | `throw` statements to convert to Result | | Try/Catch | Error handling blocks to restructure | | Console | Logging to convert to structured logging | | Paths | Hardcoded paths to convert to XDG | | Error Classes | Custom errors to map to taxonomy | | Handlers | Functions with throws to convert | | Unknowns | Complex patterns requiring review | ## Error Taxonomy Reference When mapping errors, use this reference: | Original | Outfitter | Category | |----------|-----------|----------| | `NotFoundError` | `NotFoundError` | `not_found` | | `InvalidInputError` | `ValidationError` | `validation` | | `DuplicateError` | `ConflictError` | `conflict` | | `UnauthorizedError` | `AuthError` | `auth` | | `ForbiddenError` | `PermissionError` | `permission` | | Generic `Error` | `InternalError` | `internal` | ## Effort Estimation | Count | Effort Level | |-------|--------------| | 0 | None | | 1-5 | Low | | 6-15 | Medium | | 16+ | High | ## Interpreting Results ### High-Priority Items - Functions with 3+ throw statements (complex error handling) - Files with 3+ try-catch blocks (may need restructuring) - Custom error classes with high usage counts ### Medium-Priority Items - Isolated throw statements (simple conversions) - Console logging (straightforward migration) - Hardcoded paths (mechanical replacement) ### Low-Priority Items - Documentation updates (can happen last) - Test file updates (follow handler changes) ## Next Steps After Audit 1. Review `audit-report.md` for accuracy 2. Adjust priorities in `plan/00-overview.md` 3. Begin with Stage 1 (Foundation) 4. Load `outfitter-stack:stack-patterns` for conversion guidance 5. Load `outfitter-stack:stack-templates` for scaffolding ## Constraints **Always:** - Run audit before planning adoption - Review unknowns for complex patterns - Estimate effort before committing **Never:** - Skip the audit phase - Underestimate try-catch complexity - Ignore custom error classes ## Related Skills - `outfitter-stack:stack-patterns` - Target patterns reference - `outfitter-stack:stack-templates` - Component templates - `outfitter-stack:stack-review` - Verify compliance