npm - xtrm-tools - Versions diffs - 2.3.0 → 2.4.0 - Mend

xtrm-tools 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (284) hide show

package/project-skills/tdd-guard/README.md DELETED Viewed

@@ -1,398 +0,0 @@
-# TDD Guard
-[![npm version](https://badge.fury.io/js/tdd-guard.svg)](https://www.npmjs.com/package/tdd-guard)
-[![CI](https://github.com/nizos/tdd-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/nizos/tdd-guard/actions/workflows/ci.yml)
-[![Security](https://github.com/nizos/tdd-guard/actions/workflows/security.yml/badge.svg)](https://github.com/nizos/tdd-guard/actions/workflows/security.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-Automated Test-Driven Development enforcement for Claude Code.
-## Overview
-TDD Guard ensures Claude Code follows Test-Driven Development principles. When your agent tries to skip tests or over-implement, TDD Guard blocks the action and explains what needs to happen instead.
-<p align="center">
-  <a href="https://nizar.se/uploads/videos/tdd-guard-demo.mp4">
-    <img src="docs/assets/tdd-guard-demo-screenshot.gif" alt="TDD Guard Demo" width="600">
-  </a>
-  <br>
-  <em>Click to watch TDD Guard in action</em>
-</p>
-## Features
-- **Test-First Enforcement** - Blocks implementation without failing tests
-- **Minimal Implementation** - Prevents code beyond current test requirements
-- **Lint Integration** - Enforces refactoring using your linting rules
-- **Multi-Language Support** - TypeScript, JavaScript, Python, PHP, Go, Rust, and Storybook
-- **Customizable Rules** - Adjust validation rules to match your TDD style
-- **Flexible Validation** - Choose faster or more capable models for your needs
-- **Session Control** - Toggle on and off mid-session
-## Requirements
-- Node.js 22+
-- Claude Code or Anthropic API key
-- Test framework (Jest, Vitest, Storybook, pytest, PHPUnit, Go 1.24+, or Rust with cargo/cargo-nextest)
-## Quick Start
-### 1. Install TDD Guard
-Using npm:
-```bash
-npm install -g tdd-guard
-```
-Or using Homebrew:
-```bash
-brew install tdd-guard
-```
-### 2. Add Test Reporter
-TDD Guard needs to capture test results from your test runner. Choose your language below:
-<details>
-<summary><b>JavaScript/TypeScript</b></summary>
-Choose your test runner:
-#### Vitest
-Install the [tdd-guard-vitest](https://www.npmjs.com/package/tdd-guard-vitest) reporter in your project:
-```bash
-npm install --save-dev tdd-guard-vitest
-```
-Add to your `vitest.config.ts`:
-```typescript
-import { defineConfig } from 'vitest/config'
-import { VitestReporter } from 'tdd-guard-vitest'
-export default defineConfig({
-  test: {
-    reporters: [
-      'default',
-      new VitestReporter('/Users/username/projects/my-app'),
-    ],
-  },
-})
-```
-#### Jest
-Install the [tdd-guard-jest](https://www.npmjs.com/package/tdd-guard-jest) reporter in your project:
-```bash
-npm install --save-dev tdd-guard-jest
-```
-Add to your `jest.config.ts`:
-```typescript
-import type { Config } from 'jest'
-const config: Config = {
-  reporters: [
-    'default',
-    [
-      'tdd-guard-jest',
-      {
-        projectRoot: '/Users/username/projects/my-app',
-      },
-    ],
-  ],
-}
-export default config
-```
-**Note:** For both Vitest and Jest, specify the project root path when your test config is not at the project root (e.g., in workspaces or monorepos). This ensures TDD Guard can find the test results. See the reporter configuration docs for more details:
-- [Vitest configuration](reporters/vitest/README.md#configuration)
-- [Jest configuration](reporters/jest/README.md#configuration)
-#### Storybook
-Install the [tdd-guard-storybook](https://www.npmjs.com/package/tdd-guard-storybook) reporter in your project:
-```bash
-npm install --save-dev tdd-guard-storybook
-```
-Add to your `.storybook/test-runner.js`:
-```javascript
-const { getJestConfig } = require('@storybook/test-runner')
-const { StorybookReporter } = require('tdd-guard-storybook')
-module.exports = {
-  ...getJestConfig(),
-  reporters: [
-    'default',
-    [
-      StorybookReporter,
-      {
-        projectRoot: '/Users/username/projects/my-app',
-      },
-    ],
-  ],
-}
-```
-**Note:** Storybook test-runner uses Jest under the hood, so the reporter integrates via Jest's reporter API. Specify the project root path when your Storybook config is not at the project root. See the [Storybook reporter configuration](reporters/storybook/README.md#configuration) for more details.
-**Tip:** For Storybook 10+ with Vite-based frameworks, consider using [`@storybook/addon-vitest`](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) instead. This runs Storybook tests through Vitest, allowing you to use the `tdd-guard-vitest` reporter for faster test execution. See [Storybook with Vitest Addon](docs/storybook-vitest-addon.md) for setup instructions.
-</details>
-<details>
-<summary><b>Python (pytest)</b></summary>
-Install the [tdd-guard-pytest](https://pypi.org/project/tdd-guard-pytest) reporter:
-```bash
-pip install tdd-guard-pytest
-```
-Configure the project root in your `pyproject.toml`:
-```toml
-[tool.pytest.ini_options]
-tdd_guard_project_root = "/Users/username/projects/my-app"
-```
-**Note:** Specify the project root path when your tests run from a subdirectory or in a monorepo setup. This ensures TDD Guard can find the test results. See the [pytest reporter configuration](reporters/pytest/README.md#configuration) for alternative configuration methods (pytest.ini, setup.cfg).
-</details>
-<details>
-<summary><b>PHP (PHPUnit)</b></summary>
-Install the [tdd-guard/phpunit](https://packagist.org/packages/tdd-guard/phpunit) reporter in your project:
-```bash
-composer require --dev tdd-guard/phpunit
-```
-For PHPUnit 9.x, add to your `phpunit.xml`:
-```xml
-<listeners>
-    <listener class="TddGuard\PHPUnit\TddGuardListener">
-        <arguments>
-            <string>/Users/username/projects/my-app</string>
-        </arguments>
-    </listener>
-</listeners>
-```
-For PHPUnit 10.x/11.x/12.x, add to your `phpunit.xml`:
-```xml
-<extensions>
-    <bootstrap class="TddGuard\PHPUnit\TddGuardExtension">
-        <parameter name="projectRoot" value="/Users/username/projects/my-app"/>
-    </bootstrap>
-</extensions>
-```
-**Note:** Specify the project root path when your phpunit.xml is not at the project root (e.g., in subdirectories or monorepos). This ensures TDD Guard can find the test results. The reporter saves results to `.claude/tdd-guard/data/test.json`.
-</details>
-<details>
-<summary><b>Go</b></summary>
-Install the tdd-guard-go reporter:
-```bash
-go install github.com/nizos/tdd-guard/reporters/go/cmd/tdd-guard-go@latest
-```
-Pipe `go test -json` output to the reporter:
-```bash
-go test -json ./... 2>&1 | tdd-guard-go -project-root /Users/username/projects/my-app
-```
-For Makefile integration:
-```makefile
-test:
-	go test -json ./... 2>&1 | tdd-guard-go -project-root /Users/username/projects/my-app
-```
-**Note:** The reporter acts as a filter that passes test output through unchanged while capturing results for TDD Guard. See the [Go reporter configuration](reporters/go/README.md#configuration) for more details.
-</details>
-<details>
-<summary><b>Rust</b></summary>
-Install the [tdd-guard-rust](https://crates.io/crates/tdd-guard-rust) reporter:
-```bash
-cargo install tdd-guard-rust
-```
-Use it to capture test results from `cargo test` or `cargo nextest`:
-```bash
-# With nextest (recommended)
-cargo nextest run 2>&1 | tdd-guard-rust --project-root /Users/username/projects/my-app --passthrough
-# With cargo test
-cargo test -- -Z unstable-options --format json 2>&1 | tdd-guard-rust --project-root /Users/username/projects/my-app --passthrough
-```
-For Makefile integration:
-```makefile
-test:
-	cargo nextest run 2>&1 | tdd-guard-rust --project-root $(PWD) --passthrough
-```
-**Note:** The reporter acts as a filter that passes test output through unchanged while capturing results for TDD Guard. See the [Rust reporter configuration](reporters/rust/README.md#configuration) for more details.
-</details>
-### 3. Configure Claude Code Hooks
-TDD Guard uses hooks to validate operations and provide convenience features like quick toggle commands and automatic session management.
-Choose either interactive or manual setup below:
-<details>
-<summary><b>Interactive Setup</b></summary>
-Type `/hooks` in Claude Code to open the hooks menu, then configure each hook. Use the same location for all hooks. See [Settings File Locations](docs/configuration.md#settings-file-locations) for guidance.
-**PreToolUse Hook**
-1. Select `PreToolUse - Before tool execution`
-2. Choose `+ Add new matcher...` and enter: `Write|Edit|MultiEdit|TodoWrite|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol`
-3. Select `+ Add new hook...` and enter: `node "$CLAUDE_PROJECT_DIR/.claude/hooks/tdd-guard-pretool-bridge.cjs"`
-4. Choose where to save
-**UserPromptSubmit Hook**
-1. Select `UserPromptSubmit - When the user submits a prompt`
-2. Select `+ Add new hook...` and enter: `tdd-guard`
-3. Choose same location as PreToolUse
-**SessionStart Hook**
-1. Select `SessionStart - When a new session is started`
-2. Select `+ Add new matcher...` and enter: `startup|resume|clear`
-3. Select `+ Add new hook...` and enter: `tdd-guard`
-4. Choose same location as previous hooks
-</details>
-<details>
-<summary><b>Manual Configuration</b></summary>
-If you prefer to edit settings files directly, add all three hooks to your chosen settings file. See [Settings File Locations](docs/configuration.md#settings-file-locations) to choose the appropriate file:
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit|TodoWrite|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/tdd-guard-pretool-bridge.cjs\""
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "tdd-guard"
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "tdd-guard"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-</details>
-**Note**: The pretool bridge skips non-code files (for example `.md`) and forwards code edits to `tdd-guard`, which avoids false positives on documentation-only changes.
-## Additional Configuration
-- [Custom instructions](docs/custom-instructions.md) - Customize TDD validation rules
-- [Lint integration](docs/linting.md) - Automated refactoring support
-- [Strengthening enforcement](docs/enforcement.md) - Prevent agents from bypassing validation
-- [Ignore patterns](docs/ignore-patterns.md) - Control which files are validated
-- [Validation Model](docs/validation-model.md) - Choose faster or more capable model
-## Security Notice
-As stated in the [Claude Code Hooks documentation](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations):
-> Hooks execute shell commands with your full user permissions without confirmation. You are responsible for ensuring your hooks are safe and secure. Anthropic is not liable for any data loss or system damage resulting from hook usage.
-We share this information for transparency. Please read the full [security considerations](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations) before using hooks.
-TDD Guard runs with your user permissions and has access to your file system. We follow security best practices including automated security scanning, dependency audits, and test-driven development. Review the source code if you have security concerns.
-## Roadmap
-- Add support for more testing frameworks (Mocha, unittest, etc.)
-- Add support for additional programming languages (Ruby, Java, C#, etc.)
-- Validate file modifications made through MCPs and shell commands
-- Add integration for OpenCode and other vendor-agnostic AI coding tools
-- Encourage meaningful refactoring opportunities when tests are green
-- Add support for multiple concurrent sessions per project
-## Development
-- [Development Guide](DEVELOPMENT.md) - Setup instructions and development guidelines
-- [Architecture Decision Records](docs/adr/) - Technical design decisions and rationale
-## Contributing
-Contributions are welcome! Feel free to submit issues and pull requests.
-**Contributors:**
-- Python/pytest support: [@Durafen](https://github.com/Durafen)
-- PHP/PHPUnit support: [@wazum](https://github.com/wazum)
-- Rust/cargo support: [@104hp6u](https://github.com/104hp6u)
-- Go support: [@sQVe](https://github.com/sQVe), [@wizzomafizzo](https://github.com/wizzomafizzo)
-- Storybook support: [@akornmeier](https://github.com/akornmeier)
-## Support
-- [Configuration](docs/configuration.md) - Complete settings documentation
-- [Discussions](https://github.com/nizos/tdd-guard/discussions) - Ask questions and share ideas
-- [Issues](https://github.com/nizos/tdd-guard/issues) - Report bugs and request features
-## License
-[MIT](LICENSE)

package/project-skills/tdd-guard/docs/adr/001-claude-session-subdirectory.md DELETED Viewed

@@ -1,52 +0,0 @@
-# ADR-001: Execute Claude CLI from Subdirectory for Session Management
-## Status
-Accepted
-## Context
-The TDD Guard validation system creates a new Claude session for each validation operation when running `claude` commands. This results in session list clutter and makes it difficult to track the actual development sessions.
-We considered two approaches:
-1. Clear the context before each validation using `/clear` command
-2. Run the Claude CLI from a subdirectory to isolate validation sessions
-The first approach has limitations:
-- Cannot clear and ask a question in the same command
-- Would require multiple command executions
-- Still shows all sessions in the same directory listing
-## Decision
-We will execute all Claude validation commands from a `.claude` subdirectory within the project root.
-Implementation details:
-- Create `.claude` directory if it doesn't exist
-- Set the `cwd` option in `execSync` to the subdirectory path
-- The `.claude` directory itself is not ignored (contains settings.json which should be tracked)
-- User-specific files like `.claude/settings.local.json` should already be in `.gitignore`
-## Consequences
-### Positive
-- Validation sessions are isolated from development sessions
-- No cluttering of the main project's session list
-- Automatic trust inheritance from parent directory
-- Simple implementation with minimal code changes
-- No impact on validation functionality
-### Negative
-- Creates an additional directory in the project
-- Slightly increases complexity in the model client
-- Sessions are less visible (though this is mostly a benefit)
-### Neutral
-- All validation sessions will appear in the `.claude` subdirectory listing
-- Developers need to know to look in `.claude` for validation session history

package/project-skills/tdd-guard/docs/adr/002-secure-claude-binary-path.md DELETED Viewed

@@ -1,56 +0,0 @@
-# ADR-002: Secure Claude Binary Path Configuration
-## Status
-Accepted
-## Context
-CodeQL security scanning identified a potential command injection vulnerability in `ClaudeModelClient` where the Claude binary path is taken from an environment variable (`CLAUDE_BINARY_PATH`) and interpolated into a shell command executed via `execSync`.
-The vulnerability occurs because:
-- Environment variables can be manipulated by attackers
-- Shell metacharacters in the path could be interpreted, allowing arbitrary command execution
-- For example, setting `CLAUDE_BINARY_PATH="claude; rm -rf /"` would execute both commands
-We considered several approaches:
-1. **Use execFileSync instead of execSync** - Avoids shell interpretation entirely
-2. **Validate/sanitize the binary path** - Check for allowed characters only
-3. **Use shell-quote library** - Properly escape shell metacharacters
-4. **Boolean flag for predefined paths** - Switch between hardcoded safe paths
-## Decision
-We will use a boolean environment variable `USE_LOCAL_CLAUDE` to switch between two hardcoded, safe paths:
-- When `USE_LOCAL_CLAUDE=true`: Use `$HOME/.claude/local/claude`
-- Otherwise: Use system `claude` command
-Additionally, we will:
-- Implement the path logic in `ClaudeModelClient` rather than `Config` class
-- Use `execFileSync` instead of `execSync` to prevent shell interpretation
-- Keep the Config class focused on just providing the boolean flag
-## Consequences
-### Positive
-- **Eliminates injection risk** - No user-controlled input in command construction
-- **Simple and secure** - Only two possible paths, both hardcoded
-- **Clear intent** - Boolean flag clearly indicates local vs system Claude
-- **Separation of concerns** - Config provides settings, ModelClient handles implementation
-- **Future flexibility** - ModelClient can handle OS-specific paths internally
-### Negative
-- **Less flexible** - Users cannot specify custom installation paths
-- **Requires code changes** - Adding new paths requires updating the code
-- **Platform-specific paths** - May need adjustment for different operating systems
-### Neutral
-- Migration from `CLAUDE_BINARY_PATH` to `USE_LOCAL_CLAUDE` for existing users
-- Documentation needs to be updated to reflect the new configuration approach

package/project-skills/tdd-guard/docs/adr/003-remove-configurable-data-directory.md DELETED Viewed

@@ -1,56 +0,0 @@
-# ADR-003: Remove Configurable Data Directory
-## Status
-Accepted
-## Context
-A security review identified a potential path traversal vulnerability in TDD Guard where the data directory path is taken from an environment variable (`TDD_DATA_DIR`) and used directly for file system operations without validation.
-The vulnerability occurs because:
-- Environment variables can be manipulated by attackers
-- Path traversal sequences (`../`) in the path could escape the intended directory
-- For example, setting `TDD_DATA_DIR="../../../../etc"` would write files to system directories
-- The application writes files like `test.txt`, `todo.json`, and `modifications.json` to this directory
-We considered several approaches:
-1. **Validate and sanitize the path** - Check for `../` sequences and resolve to absolute paths
-2. **Restrict to project subdirectories** - Ensure the path stays within the project root
-3. **Use a whitelist of allowed paths** - Only allow specific predefined directories
-4. **Remove the configuration entirely** - Hardcode the data directory path
-## Decision
-We will remove the `TDD_DATA_DIR` environment variable and hardcode the data directory path to `.claude/tdd-guard/data` in the Config class.
-The implementation will:
-- Remove `TDD_DATA_DIR` from environment variable processing
-- Hardcode `dataDir` to `.claude/tdd-guard/data` in the Config constructor
-- Keep the existing Config class interface unchanged for dependent code
-- Remove documentation about `TDD_DATA_DIR` from `.env.example`, README, and CLAUDE.md
-## Consequences
-### Positive
-- **Eliminates path traversal risk** - No user-controlled input for file paths
-- **Simpler implementation** - No validation or sanitization code needed
-- **Consistent data location** - All TDD Guard data in a predictable location
-- **Better security posture** - Follows principle of least privilege
-- **No breaking changes for code** - Config class interface remains the same
-### Negative
-- **Less flexible** - Users cannot customize where TDD Guard stores its data
-- **Potential disk space issues** - Users cannot redirect to different drives/partitions
-- **Testing limitations** - Integration tests cannot use isolated data directories
-### Neutral
-- The data stored (test results, todos, modifications) is operational/temporary
-- Most users likely never customized this path anyway
-- Follows the same security-first approach as ADR-002

package/project-skills/tdd-guard/docs/adr/004-monorepo-architecture.md DELETED Viewed

@@ -1,64 +0,0 @@
-# ADR-004: Monorepo Architecture for Multi-Language Support
-## Status
-Accepted
-## Context
-TDD Guard originally published a single package to both npm and PyPI, with all test framework reporters mixed together in the src directory. This created several problems:
-- **Language mixing** - JavaScript and Python code in the same package
-- **Publishing complexity** - Single codebase published to multiple package registries
-- **Package bloat** - Users installed code for all languages even if using only one
-- **Contribution barriers** - Adding new reporters required navigating the entire codebase
-We considered several approaches:
-1. **Keep monolithic structure** - Continue with mixed languages in one package
-2. **Separate repositories** - Create individual repos for each reporter
-3. **Monorepo with workspaces** - Keep one repo but separate packages
-## Decision
-We will restructure TDD Guard as a monorepo using npm workspaces, with each reporter as a separate package.
-The new structure:
-```
-tdd-guard/                  # Main CLI package (npm)
-├── src/                    # Core functionality and shared code
-└── package.json
-reporters/
-├── vitest/                 # tdd-guard-vitest package (npm)
-│   └── package.json
-└── pytest/                 # tdd-guard-pytest package (PyPI)
-    └── pyproject.toml
-```
-Implementation details:
-- Main package exports shared functionality (Storage, Config, contracts)
-- Each reporter is a standalone package with its own version
-- Vitest reporter imports shared code from 'tdd-guard' package
-- Python reporter is self-contained (no JavaScript dependencies)
-## Consequences
-### Positive
-- **Clean separation** - Each language has its own package and tooling
-- **Smaller packages** - Users only install what they need
-- **Independent releases** - Can update reporters without touching others
-- **Easier contributions** - Clear boundaries for adding new reporters
-### Negative
-- **Multiple packages to maintain** - More release overhead
-- **Build complexity** - Must ensure correct build order during development
-### Neutral
-- Users now install two packages (CLI + reporter) instead of one
-- Each package has its own documentation and version number

package/project-skills/tdd-guard/docs/adr/005-claude-project-dir-support.md DELETED Viewed

@@ -1,55 +0,0 @@
-# ADR-005: Support CLAUDE_PROJECT_DIR for Consistent Data Storage
-## Status
-Accepted
-## Context
-TDD Guard stores data in `.claude/tdd-guard/data` relative to the current working directory. This creates issues when:
-- Users run commands from subdirectories (e.g., `cd src && npm test`)
-- Claude Code executes commands from different locations within a project
-- Multiple `.claude` directories are created at different levels
-Previously, users had to configure `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` in Claude Code to ensure commands always run from the project root. This required additional configuration and restricted how developers could use Claude Code.
-Claude Code provides the `CLAUDE_PROJECT_DIR` environment variable that always points to the project root, regardless of where commands are executed. This is part of Claude Code's [security best practices](https://docs.anthropic.com/en/docs/claude-code/hooks#security-best-practices).
-## Decision
-We will use `CLAUDE_PROJECT_DIR` when available to determine the base path for TDD Guard's data directory.
-The implementation:
-- Check if `CLAUDE_PROJECT_DIR` is set and valid
-- Use it as the base path for `.claude/tdd-guard/data` if available
-- Fall back to current working directory if not set
-- Apply security validations to prevent path traversal attacks
-- Reporter-provided `projectRoot` takes precedence over `CLAUDE_PROJECT_DIR`
-Security validations include:
-- Validate `CLAUDE_PROJECT_DIR` is an absolute path
-- Prevent path traversal by checking for `..` sequences
-- Ensure current working directory is within `CLAUDE_PROJECT_DIR`
-When validation fails, TDD Guard throws a descriptive error and the operation is blocked, preventing any file system access with invalid paths.
-## Consequences
-### Positive
-- **Consistent data location** - Data is always stored at the project root
-- **No user configuration needed** - Works automatically with Claude Code
-- **Better developer experience** - Can run commands from any project subdirectory
-- **Maintains security** - Path validation prevents directory traversal attacks
-### Negative
-- **Additional validation code** - Security checks add complexity, but this is centralized in the Config class
-### Neutral
-- Falls back gracefully when environment variable is not present
-- Replaces the need for `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` configuration