# Clone the repository
git clone <repository-url>
cd ai_toolbox

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Type checking (fast, no emit)
npm run typecheck

# Linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Build for production
npm run build

# Run all tests
npm test

// ✅ GOOD: Typed params interface
interface ReadFileParams {
  file_name: string;
  max_length?: number;
}

// ✅ GOOD: Proper error handling
function handleError(error: unknown): { success: false; error: string } {
  const message = error instanceof Error ? error.message : String(error);
  return { success: false, error: message };
}

// ❌ BAD: Using 'any'
async function badExample(params: any) { /* ... */ }

tools.push(tool({
  name: 'tool_name',
  description: 'Clear description of what the tool does.',
  parameters: {
    param1: z.string().describe('Parameter description'),
    param2: z.number().int().min(1).optional().default(5).describe('Optional param'),
  },
  implementation: async ({ param1, param2 }: TypedParamsInterface) => {
    try {
      // 1. Validate inputs
      // 2. Perform operation
      // 3. Return structured result
      return { success: true, data: { /* result */ } };
    } catch (error) {
      return handleError(error);
    }
  },
}));

// Success response
return { success: true, data: { /* result data */ } };

// Error response
return { success: false, error: 'Clear error message' };

# Run all tests
npm test

# Run specific test file
npx jest tests/security.test.ts

# Run with coverage
npx jest --coverage

// Example test structure
describe('Security Module', () => {
  describe('validatePath', () => {
    it('should reject directory traversal', () => {
      expect(validatePath('../etc/passwd', '/safe/dir')).toBe(false);
    });

    it('should allow valid paths', () => {
      expect(validatePath('subdir/file.txt', '/safe/dir')).toBe(true);
    });
  });
});

## Description
Brief description of the changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature/tool
- [ ] Security improvement
- [ ] Documentation update
- [ ] Performance optimization

## Testing
- [ ] All tests pass
- [ ] Manual testing completed
- [ ] New tests added (if applicable)

## Security Review
- [ ] No new security vulnerabilities introduced
- [ ] Input validation implemented
- [ ] Tool gating applied (if dangerous)

### tool_name

**Description**: What the tool does.

**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| param1 | `string` | Yes | Description |
| param2 | `number` | No | Description (default: 5) |

**Returns**: `{ success: boolean, data?: object, error?: string }`

**Example**:
```json
{
  "param1": "value",
  "param2": 10
}

---

## 🏗️ Project Structure Reference

### Adding a New Tool Category

1. Create a new file in `src/tools/` (e.g., `newCategoryTools.ts`)
2. Export a `registerNewCategoryTools(config)` function
3. Import and register in `src/toolsProvider.ts`
4. Add config toggle in `src/config.ts` (both schema and DEFAULT_CONFIG)
5. Add UI schematic field in `configSchematics` builder chain
6. Add tests in `tests/`
7. Update documentation (README, TOOLS_REFERENCE, CHANGELOG, ARCHITECTURE)

---

## 🆘 Getting Help

- **Issues**: File a GitHub issue for bugs or feature requests
- **Discussions**: Use GitHub Discussions for questions
- **Security Issues**: See [SECURITY.md](SECURITY.md) for responsible disclosure

---

## 📜 Code of Conduct

Be respectful, constructive, and inclusive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/).

---

## 🛡️ Testing ContextGuard Features (v1.4.1)

### UI Controls Verification

```bash
# 1. Open LM Studio → Plugins → AI Toolbox → ⚙️ Settings
# 2. Scroll to "🧠 ContextGuard Token Management" section
# 3. Verify all 6 controls are present:
#    - [ ] 🧠 ContextGuard Token Management (toggle)
#    - [ ] 📊 Token Limit Before Compression (numeric, 1K-200K)
#    - [ ] 🔍 Smart File Reading (toggle)
#    - [ ] 🤖 Summary Model Name (text input)
#    - [ ] 📌 Terminal Output Filtering (toggle)
#    - [ ] 📏 Max Terminal Output Length (numeric, 100-20K)

# 1. Set Token Limit to a low value (e.g., 10,000)
# 2. Have a long conversation or paste large content
# 3. When token count exceeds ~9,000 (90% of limit), compression triggers
# 4. Verify visual indicator appears with:
#    - [ ] 🧠 Emoji header
#    - [ ] Number of messages compressed
#    - [ ] Tokens before → after (e.g., "~85k → ~42k")
#    - [ ] Percentage saved (e.g., "Saved ~43,000 tokens (~51%)")
#    - [ ] Timestamp
#    - [ ] Visual separator lines

# 1. Create a large file (>10KB) with specific keywords:
cat > test_file.js << 'EOF'
// Line 1-100: filler content
function calculateTax(income) {
  return income * 0.25;
}
// More filler...
function processPayment(amount) {
  // Payment logic
}
// Even more filler...
EOF

# 2. Ask the AI about "calculateTax" function
# 3. Verify only relevant lines around that keyword are returned
# 4. Toggle Smart File Reading OFF and verify full file is read instead

# 1. Run a command with large output:
npm install --verbose 2>&1 | head -n 5000

# 2. Verify output is truncated to configured length (default: 2,000 chars)
# 3. Check for truncation indicator: "... [Output truncated: X lines hidden] ..."
# 4. Toggle Terminal Output Filtering OFF and verify full output

git checkout -b feature/description-of-change

npm test
npm run typecheck
npm run lint

npm run build

feat: add new tool category for image processing
fix: resolve path validation edge case on Windows
docs: update README with configuration table