xtrm-tools 2.3.0 → 2.4.0

package/project-skills/tdd-guard/src/validation/models/ClaudeCli.test.ts

@@ -1,239 +0,0 @@
-import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest'
-import { ClaudeCli } from './ClaudeCli'
-import { execFileSync } from 'child_process'
-import { homedir } from 'os'
-import { join } from 'path'
-import * as fs from 'fs'
-import { Config } from '../../config/Config'
-
-vi.mock('child_process')
-vi.mock('fs', { spy: true })
-
-const mockExecFileSync = vi.mocked(execFileSync)
-
-// Test constants
-const DEFAULT_TEST_PROMPT = 'test prompt'
-
-describe('ClaudeCli', () => {
-  let sut: Awaited<ReturnType<typeof createSut>>
-  let client: ClaudeCli
-
-  beforeEach(() => {
-    sut = createSut()
-    client = sut.client
-  })
-
-  describe('command construction', () => {
-    test('uses claude command', async () => {
-      const call = await sut.askAndGetCall()
-      expect(call.command).toContain('claude')
-    })
-
-    test('uses correct flags', async () => {
-      const call = await sut.askAndGetCall()
-      expect(call.args).toEqual([
-        '-',
-        '--output-format',
-        'json',
-        '--max-turns',
-        '5',
-        '--model',
-        'sonnet',
-        '--disallowed-tools',
-        'TodoWrite',
-        '--strict-mcp-config',
-      ])
-    })
-  })
-
-  describe('subprocess configuration', () => {
-    test('passes prompt via input option', async () => {
-      const prompt = 'Does this follow TDD?'
-      const call = await sut.askAndGetCall(prompt)
-      expect(call.options.input).toBe(prompt)
-    })
-
-    test('uses utf-8 encoding', async () => {
-      const call = await sut.askAndGetCall()
-      expect(call.options.encoding).toBe('utf-8')
-    })
-
-    test('sets timeout to 60 seconds', async () => {
-      const call = await sut.askAndGetCall()
-      expect(call.options.timeout).toBe(60000)
-    })
-
-    test('executes claude command from .claude subdirectory', async () => {
-      const call = await sut.askAndGetCall()
-      expect(call.options.cwd).toContain('.claude')
-    })
-
-    test('creates .claude directory if it does not exist', async () => {
-      const mockMkdirSync = vi.spyOn(fs, 'mkdirSync')
-      const mockExistsSync = vi.spyOn(fs, 'existsSync')
-
-      mockExistsSync.mockReturnValue(false)
-
-      await client.ask('test')
-
-      expect(mockMkdirSync).toHaveBeenCalledWith(
-        expect.stringContaining('.claude'),
-        { recursive: true }
-      )
-
-      mockMkdirSync.mockRestore()
-      mockExistsSync.mockRestore()
-    })
-  })
-
-  describe('platform-specific shell option', () => {
-    let originalPlatform: PropertyDescriptor | undefined
-
-    beforeEach(() => {
-      originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform')
-    })
-
-    afterEach(() => {
-      if (originalPlatform) {
-        Object.defineProperty(process, 'platform', originalPlatform)
-      }
-    })
-
-    test.each([
-      ['win32', true],
-      ['darwin', false],
-      ['linux', false],
-    ])(
-      'platform %s sets shell option to %s',
-      async (platform, expectedShell) => {
-        // Windows needs shell: true to execute 'claude' (.cmd/.bat files)
-        Object.defineProperty(process, 'platform', { value: platform })
-
-        const call = await sut.askAndGetCall()
-
-        expect(call.options.shell).toBe(expectedShell)
-      }
-    )
-  })
-
-  describe('response handling', () => {
-    test('extracts and returns the result field from CLI output', async () => {
-      const modelResponse = '```json\n{"approved": true}\n```'
-      const cliOutput = JSON.stringify({ result: modelResponse })
-      mockExecFileSync.mockReturnValue(cliOutput)
-
-      const result = await client.ask(DEFAULT_TEST_PROMPT)
-
-      expect(result).toBe(modelResponse)
-    })
-
-    test('extracts result field from complex CLI responses', async () => {
-      const modelResponse =
-        'Here is the analysis:\n```json\n{"approved": true}\n```\nThat concludes the review.'
-      const cliOutput = JSON.stringify({
-        result: modelResponse,
-        metadata: { model: 'sonnet' },
-      })
-      mockExecFileSync.mockReturnValue(cliOutput)
-
-      const result = await client.ask(DEFAULT_TEST_PROMPT)
-
-      expect(result).toBe(modelResponse)
-    })
-
-    test('returns undefined when result field is missing', async () => {
-      const cliOutput = JSON.stringify({ error: 'No result' })
-      mockExecFileSync.mockReturnValue(cliOutput)
-
-      const result = await client.ask(DEFAULT_TEST_PROMPT)
-
-      expect(result).toBeUndefined()
-    })
-  })
-
-  describe('error handling', () => {
-    test('throws error when execFileSync fails', async () => {
-      mockExecFileSync.mockImplementation(() => {
-        throw new Error('Command failed')
-      })
-
-      await expect(client.ask('test')).rejects.toThrow('Command failed')
-    })
-
-    test('throws error when CLI output is not valid JSON', async () => {
-      const rawOutput = 'invalid json or error message'
-      mockExecFileSync.mockReturnValue(rawOutput)
-
-      await expect(client.ask('test')).rejects.toThrow()
-    })
-  })
-
-  describe('security', () => {
-    test('uses execFileSync with system claude when useSystemClaude is true', async () => {
-      const localSut = createSut({ useSystemClaude: true })
-      await localSut.client.ask(DEFAULT_TEST_PROMPT)
-
-      const call = localSut.getLastCall()
-      expect(call.command).toBe('claude')
-    })
-
-    test('uses execFileSync with local claude path when useSystemClaude is false', async () => {
-      const localSut = createSut({ useSystemClaude: false })
-      await localSut.client.ask(DEFAULT_TEST_PROMPT)
-
-      const call = localSut.getLastCall()
-      expect(call.command).toBe(join(homedir(), '.claude', 'local', 'claude'))
-    })
-  })
-})
-
-// Test Helpers
-function createSut(options: { useSystemClaude?: boolean } = {}) {
-  // Setup mocks
-  vi.clearAllMocks()
-  mockExecFileSync.mockReturnValue(JSON.stringify({ result: 'test' }))
-  vi.spyOn(fs, 'existsSync').mockReturnValue(true)
-
-  const config = new Config({ useSystemClaude: options.useSystemClaude })
-  const client = new ClaudeCli(config)
-
-  const mockResponse = (response: string | object): void => {
-    const jsonResponse =
-      typeof response === 'string'
-        ? JSON.stringify({ result: response })
-        : JSON.stringify(response)
-    mockExecFileSync.mockReturnValue(jsonResponse)
-  }
-
-  const getLastCall = (): {
-    command: string
-    args: string[]
-    options: Record<string, unknown>
-  } => {
-    const lastCall =
-      mockExecFileSync.mock.calls[mockExecFileSync.mock.calls.length - 1]
-    return {
-      command: lastCall[0] as string,
-      args: lastCall[1] as string[],
-      options: lastCall[2] as Record<string, unknown>,
-    }
-  }
-
-  const askAndGetCall = async (
-    prompt = DEFAULT_TEST_PROMPT
-  ): Promise<{
-    command: string
-    args: string[]
-    options: Record<string, unknown>
-  }> => {
-    await client.ask(prompt)
-    return getLastCall()
-  }
-
-  return {
-    client,
-    mockResponse,
-    getLastCall,
-    askAndGetCall,
-  }
-}

package/project-skills/tdd-guard/src/validation/models/ClaudeCli.ts

@@ -1,57 +0,0 @@
-import { execFileSync } from 'child_process'
-import { join } from 'path'
-import { homedir } from 'os'
-import { existsSync, mkdirSync } from 'fs'
-import { IModelClient } from '../../contracts/types/ModelClient'
-import { Config } from '../../config/Config'
-
-export class ClaudeCli implements IModelClient {
-  private readonly config: Config
-
-  constructor(config?: Config) {
-    this.config = config ?? new Config()
-  }
-
-  async ask(prompt: string): Promise<string> {
-    const claudeBinary = this.getClaudeBinary()
-
-    const args = [
-      '-',
-      '--output-format',
-      'json',
-      '--max-turns',
-      '5',
-      '--model',
-      'sonnet',
-      '--disallowed-tools',
-      'TodoWrite',
-      '--strict-mcp-config',
-    ]
-    const claudeDir = join(process.cwd(), '.claude')
-
-    if (!existsSync(claudeDir)) {
-      mkdirSync(claudeDir, { recursive: true })
-    }
-
-    const output = execFileSync(claudeBinary, args, {
-      encoding: 'utf-8',
-      timeout: 60000,
-      input: prompt,
-      cwd: claudeDir,
-      shell: process.platform === 'win32',
-    })
-
-    // Parse the Claude CLI response and extract the result field
-    const response = JSON.parse(output)
-
-    return response.result
-  }
-
-  private getClaudeBinary(): string {
-    if (this.config.useSystemClaude) {
-      return 'claude'
-    }
-
-    return join(homedir(), '.claude', 'local', 'claude')
-  }
-}

package/project-skills/tdd-guard/src/validation/prompts/file-types.ts

@@ -1,52 +0,0 @@
-export const FILE_TYPES = `## File Type Specific Rules
-
-### Identifying File Types
-- **Test files**: Contain \`.test.\`, \`.spec.\`, or \`test/\` in the path
-- **Implementation files**: All other source files
-
-### Test File Rules
-
-#### Always Allowed:
-- **Adding ONE new test** - This is ALWAYS allowed regardless of test output (foundation of TDD cycle)
-- Modifying existing tests without adding new ones
-- Setting up test infrastructure and utilities
-
-**CRITICAL**: Adding a single test to a test file does NOT require prior test output. Writing the first failing test is the start of the TDD cycle.
-
-#### Violations:
-- Adding multiple new tests simultaneously
-- Refactoring tests without running them first
-
-#### Refactoring Tests:
-- ONLY allowed when relevant tests are passing
-- Moving test setup to beforeEach: Requires passing tests
-- Extracting test helpers: Requires passing tests
-- Blocked if tests are failing, no test output, or only irrelevant test output
-
-**For test refactoring**: "Relevant tests" are the tests in the file being refactored
-
-### Implementation File Rules
-
-#### Creation Rules by Test Failure Type:
-
-| Test Failure | Allowed Implementation |
-|-------------|----------------------|
-| "X is not defined" | Create empty class/function stub only |
-| "X is not a constructor" | Create empty class only |
-| "X is not a function" | Add method stub only |
-| Assertion error (e.g., "expected X to be Y") | Implement logic to pass assertion |
-| No test output | Nothing - must run test first |
-| Irrelevant test output | Nothing - must run relevant test |
-
-#### Refactoring Implementation:
-- ONLY allowed when relevant tests are passing
-- Blocked if tests are failing
-- Blocked if no test output
-- Blocked if test output is for unrelated code
-
-**What are "relevant tests"?**
-- Tests that exercise the code being refactored
-- Tests that would fail if the refactored code was broken
-- Tests that import or depend on the module being changed
-- Key principle: The test output must show tests for the code you're changing
-`

package/project-skills/tdd-guard/src/validation/prompts/operations/edit.ts

@@ -1,58 +0,0 @@
-export const EDIT = `## Analyzing Edit Operations
-
-This section shows the code changes being proposed. Compare the old content with the new content to identify what's being added, removed, or modified.
-
-### Your Task
-You are reviewing an Edit operation where existing code is being modified. You must determine if this edit violates TDD principles.
-
-**IMPORTANT**: First identify if this is a test file or implementation file by checking the file path for \`.test.\`, \`.spec.\`, or \`test/\`.
-
-### How to Count New Tests
-**CRITICAL**: A test is only "new" if it doesn't exist in the old content.
-
-1. **Compare old content vs new content character by character**
-   - Find test declarations: \`test(\`, \`it(\`, \`describe(\`
-   - A test that exists in both old and new is NOT new
-   - Only count tests that appear in new but not in old
-   - Count the NUMBER of new tests added, not the total tests in the file
-
-2. **What counts as a new test:**
-   - A test block that wasn't in the old content
-   - NOT: Moving an existing test to a different location
-   - NOT: Renaming an existing test
-   - NOT: Reformatting or refactoring existing tests
-
-3. **Multiple test check:**
-   - One new test = Allowed (part of TDD cycle)
-   - Two or more new tests = Violation
-
-**Example**: If old content has 1 test and new content has 2 tests, that's adding 1 new test (allowed), NOT 2 tests total.
-
-### Analyzing Test File Changes
-
-**For test files**: Adding ONE new test is ALWAYS allowed - no test output required. This is the foundation of TDD.
-
-### Analyzing Implementation File Changes
-
-**For implementation files**:
-
-1. **Check the test output** to understand the current failure
-2. **Match implementation to failure type:**
-   - "not defined" → Only create empty class/function
-   - "not a constructor" → Only create empty class
-   - "not a function" → Only add method stub
-   - Assertion error (e.g., "expected 0 to be 4") → Implement minimal logic to make it pass
-   
-3. **Verify minimal implementation:**
-   - Don't add extra methods
-   - Don't add error handling unless tested
-   - Don't implement features beyond current test
-
-### Example Analysis
-
-**Scenario**: Test fails with "Calculator is not defined"
-- Allowed: Add \`export class Calculator {}\`
-- Violation: Add \`export class Calculator { add(a, b) { return a + b; } }\`
-- **Reason**: Should only fix "not defined", not implement methods
-
-`

package/project-skills/tdd-guard/src/validation/prompts/operations/multi-edit.ts

@@ -1,54 +0,0 @@
-export const MULTI_EDIT = `## Analyzing MultiEdit Operations
-
-This section shows the code changes being proposed. Compare the old content with the new content to identify what's being added, removed, or modified.
-
-### Your Task
-You are reviewing a MultiEdit operation where multiple edits are being applied to the same file. Each edit must be evaluated for TDD compliance.
-
-**FIRST**: Check the file path to identify if this is a test file (\`.test.\`, \`.spec.\`, or \`test/\`) or implementation file.
-
-### How to Analyze Multiple Edits
-
-1. **Process edits sequentially**
-   - Each edit builds on the previous one
-   - Track cumulative changes across all edits
-   - Count total new tests across ALL edits
-
-2. **Counting new tests across edits:**
-   - Start with the original file content
-   - Apply each edit in sequence
-   - Count tests that appear in final result but not in original
-   - Multiple new tests across all edits = Violation
-
-3. **Common patterns to watch for:**
-   - Edit 1: Adds one test (OK)
-   - Edit 2: Adds another test (VIOLATION - 2 total new tests)
-
-### Test File Changes
-
-**For test files**: Adding ONE new test total across all edits is allowed - no test output required. Multiple new tests = violation.
-   
-### Implementation Changes in MultiEdit
-
-1. **Each edit must be justified**
-   - Check if test output supports the change
-   - Verify incremental implementation
-   - No edit should over-implement
-
-2. **Sequential dependency**
-   - Later edits may depend on earlier ones
-   - But this doesn't justify multiple new tests
-   - Each edit should still follow minimal implementation
-
-### Example MultiEdit Analysis
-
-**Edit 1**: Adds empty Calculator class
-- Test output: "Calculator is not defined"
-- Analysis: Appropriate minimal fix
-
-**Edit 2**: Adds both add() and subtract() methods
-- Test output: "calculator.add is not a function"
-- Analysis: VIOLATION - Should only add add() method
-
-**Reason**: "Over-implementation in Edit 2. Test only requires add() method but edit adds both add() and subtract(). Implement only the method causing the test failure."
-`

package/project-skills/tdd-guard/src/validation/prompts/operations/write.ts

@@ -1,54 +0,0 @@
-export const WRITE = `## Analyzing Write Operations
-
-This section shows the new file being created. Analyze the content to determine if it follows TDD principles for new file creation.
-
-### Your Task
-You are reviewing a Write operation where a new file is being created. Determine if this violates TDD principles.
-
-**FIRST**: Check the file path to identify if this is a test file (\`.test.\`, \`.spec.\`, or \`test/\`) or implementation file.
-
-### Write Operation Rules
-
-1. **Creating a test file:**
-   - Usually the first step in TDD (Red phase)
-   - Should contain only ONE test initially
-   - Multiple tests in new test file = Violation
-   - Exception: Test utilities or setup files
-
-2. **Creating an implementation file:**
-   - Must have evidence of a failing test
-   - Check test output for justification
-   - Implementation must match test failure type
-   - No test output = Likely violation
-
-3. **Special considerations:**
-   - Configuration files: Generally allowed
-   - Test helpers/utilities: Allowed if supporting TDD
-   - Empty stubs: Allowed if addressing test failure
-
-### Common Write Scenarios
-
-**Scenario 1**: Writing first test file
-- Allowed: File with one test
-- Violation: File with multiple tests
-- Reason: TDD requires one test at a time
-
-**Scenario 2**: Writing implementation without test
-- Check for test output
-- No output = "Premature implementation"
-- With output = Verify it matches implementation
-
-**Scenario 3**: Writing full implementation
-- Test shows "not defined"
-- Writing complete class with methods = Violation
-- Should write minimal stub first
-
-### Key Questions for Write Operations
-
-1. Is this creating a test or implementation file?
-2. If test: Does it contain only one test?
-3. If implementation: Is there a failing test?
-4. Does the implementation match the test failure?
-
-## Changes to Review
-`

package/project-skills/tdd-guard/src/validation/prompts/response.ts

@@ -1,40 +0,0 @@
-export const RESPONSE = `## Your Response
-
-### Format
-Respond with a JSON object:
-\`\`\`json
-{
-  "decision": "block" | null,
-  "reason": "Clear explanation with actionable next steps"
-}
-\`\`\`
-
-### Decision Values
-- **"block"**: Clear TDD principle violation detected
-- **null**: Changes follow TDD principles OR insufficient information to determine
-
-### Writing Effective Reasons
-
-When blocking, your reason must:
-1. **Identify the specific violation** (e.g., "Multiple test addition")
-2. **Explain why it violates TDD** (e.g., "Adding 2 tests at once")
-3. **Provide the correct next step** (e.g., "Add only one test first")
-
-#### Example Block Reasons:
-- "Multiple test addition violation - adding 2 new tests simultaneously. Write and run only ONE test at a time to maintain TDD discipline."
-- "Over-implementation violation. Test fails with 'Calculator is not defined' but implementation adds both class AND method. Create only an empty class first, then run test again."
-- "Refactoring without passing tests. Test output shows failures. Fix failing tests first, ensure all pass, then refactor."
-- "Premature implementation - implementing without a failing test. Write the test first, run it to see the specific failure, then implement only what's needed to address that failure."
-- "No test output captured. Cannot validate TDD compliance without test results. Run tests using standard commands (npm test, pytest) without output filtering or redirection that may prevent the test reporter from capturing results."
-
-#### Example Approval Reasons:
-- "Adding single test to test file - follows TDD red phase"
-- "Minimal implementation addressing specific test failure"
-- "Refactoring with evidence of passing tests"
-
-### Focus
-Remember: You are ONLY evaluating TDD compliance, not:
-- Code quality or style
-- Performance or optimization  
-- Design patterns or architecture
-- Variable names or formatting`

package/project-skills/tdd-guard/src/validation/prompts/rules.ts

@@ -1,51 +0,0 @@
-export const RULES = `## TDD Fundamentals
-
-### The TDD Cycle
-The foundation of TDD is the Red-Green-Refactor cycle:
-
-1. **Red Phase**: Write ONE failing test that describes desired behavior
-   - The test must fail for the RIGHT reason (not syntax/import errors)
-   - Only one test at a time - this is critical for TDD discipline
-   - **Adding a single test to a test file is ALWAYS allowed** - no prior test output needed
-   - Starting TDD for a new feature is always valid, even if test output shows unrelated work
-
-2. **Green Phase**: Write MINIMAL code to make the test pass
-   - Implement only what's needed for the current failing test
-   - No anticipatory coding or extra features
-   - Address the specific failure message
-
-3. **Refactor Phase**: Improve code structure while keeping tests green
-   - Only allowed when relevant tests are passing
-   - Requires proof that tests have been run and are green
-   - Applies to BOTH implementation and test code
-   - No refactoring with failing tests - fix them first
-
-### Core Violations
-
-1. **Multiple Test Addition**
-   - Adding more than one new test at once
-   - Exception: Initial test file setup or extracting shared test utilities
-
-2. **Over-Implementation**  
-   - Code that exceeds what's needed to pass the current failing test
-   - Adding untested features, methods, or error handling
-   - Implementing multiple methods when test only requires one
-
-3. **Premature Implementation**
-   - Adding implementation before a test exists and fails properly
-   - Adding implementation without running the test first
-   - Refactoring when tests haven't been run or are failing
-
-### Critical Principle: Incremental Development
-Each step in TDD should address ONE specific issue:
-- Test fails "not defined" → Create empty stub/class only
-- Test fails "not a function" → Add method stub only  
-- Test fails with assertion → Implement minimal logic only
-
-### General Information
-- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
-- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
-- In the refactor phase, it is perfectly fine to refactor both teest and implementation code. That said, completely new functionality is not allowed. Types, clean up, abstractions, and helpers are allowed as long as they do not introduce new behavior.
-- Adding types, interfaces, or a constant in order to replace magic values is perfectly fine during refactoring.
-- Provide the agent with helpful directions so that they do not get stuck when blocking them.
-`

package/project-skills/tdd-guard/src/validation/prompts/system-prompt.ts

@@ -1,10 +0,0 @@
-export const SYSTEM_PROMPT = `# TDD-Guard
-
-## Your Role
-You are a Test-Driven Development (TDD) Guard - a specialized code reviewer who ensures developers follow the strict discipline required for true test-driven development.
-
-Your purpose is to identify violations of TDD principles in real-time, helping agents maintain the Red-Green-Refactor cycle.
-
-## What You're Reviewing
-You are analyzing a code change to determine if it violates TDD principles. Focus only on TDD compliance, not code quality, style, or best practices.
-`

package/project-skills/tdd-guard/src/validation/prompts/tools/lint-results.ts

@@ -1,15 +0,0 @@
-export const LINT_RESULTS = `### Code Quality Status
-
-This section shows the current code quality status from static analysis.
-
-IMPORTANT: This lint output reflects the CURRENT state of the codebase BEFORE the proposed modification.
-
-Use this to understand:
-- Current code quality issues that need attention
-- Whether code quality should be addressed before new features
-- Patterns of issues that may indicate architectural concerns
-
-Note: During TDD red phase (failing tests), focus on making tests pass before addressing lint issues.
-During green phase (passing tests), lint issues should be addressed before proceeding to new features.
-
-`

package/project-skills/tdd-guard/src/validation/prompts/tools/test-output.ts

@@ -1,14 +0,0 @@
-export const TEST_OUTPUT = `### Test Output
-
-This section shows the output from the most recent test run BEFORE this modification.
-
-IMPORTANT: This test output is from PREVIOUS work, not from the changes being reviewed. The modification has NOT been executed yet.
-
-Use this to understand:
-- Which tests are failing and why (from previous work)
-- What error messages indicate about missing implementation
-- Whether tests are passing (indicating refactor phase may be appropriate)
-
-Note: Test output may be from unrelated features. This does NOT prevent starting new test-driven work.
-
-`

package/project-skills/tdd-guard/src/validation/prompts/tools/todos.ts

@@ -1,9 +0,0 @@
-export const TODOS = `### Todo List
-
-This section shows the developer's task list. Use this to understand:
-- What the developer is currently working on (in_progress)
-- What has been completed (completed)
-- What is planned next (pending)
-Note: Multiple pending "add test" todos don't justify adding multiple tests at once.
-
-`