npm package: @openpets/json-tools
Description: Comprehensive JSON tools for schema analysis, smart search, and data exploration. Perfect for analyzing large JSON files, API responses, and complex data structures without manual parsing.
Latest version: 1.0.0

# JSON Tools Plugin

Advanced JSON analysis and search capabilities for OpenCode. This plugin provides intelligent JSON parsing, schema analysis, and powerful search functionality to help LLMs understand and explore JSON data efficiently.

## Features

### 🔍 **Schema Analysis**
- Comprehensive JSON structure analysis with type detection
- Nesting depth analysis and data type summaries
- Optional sample value extraction for exploration
- Memory-efficient processing of large JSON files

### 🔎 **Smart Search**
- Text-based search with case sensitivity options
- Path-based queries (e.g., `user.email`, `items[*].name`)
- Support for array indexing and slicing
- Search across nested structures with configurable depth
- Type-based filtering (string, number, boolean, object, array)

### 📊 **Data Intelligence**
- Automatic type detection and classification
- Array structure analysis (uniform vs mixed types)
- Object property counting and key analysis
- File size validation and memory management

## Quick Start

### Installation

```bash
cd pets/json-tools
npm install
```

### Basic Usage

```bash
# Analyze a JSON file structure
opencode run "analyze the schema of package.json"

# Search for specific values
opencode run "search for all dependencies in package.json"

# Test the plugin
opencode run "test json tools connection"
```

## Tools

### `json-tools-test-connection`

Test plugin configuration and verify all capabilities are ready.

**Usage:**
```bash
opencode run "test json tools connection"
```

### `json-tools-schema-analyze`

Analyze JSON structure and return comprehensive schema overview.

**Parameters:**
- `jsonInput` (optional): JSON string to analyze
- `filePath` (optional): Path to JSON file
- `includeSampleValues` (optional, default: false): Include sample values
- `maxDepth` (optional, default: 10): Maximum analysis depth
- `maxSamples` (optional, default: 3): Maximum samples per type

**Examples:**
```bash
# Basic schema analysis
opencode run "analyze the schema of config.json"

# With sample values
opencode run "analyze the schema of package.json with sample values"

# Custom depth limit
opencode run "analyze schema of large-data.json with max depth 5"
```

### `json-tools-search`

Search for values, patterns, or paths in JSON data.

**Parameters:**
- `query`: Search query or path expression
- `jsonInput` (optional): JSON string to search
- `filePath` (optional): Path to JSON file
- `caseSensitive` (optional, default: false): Case sensitive search
- `exactMatch` (optional, default: false): Exact vs contains matching
- `maxDepth` (optional, default: 10): Maximum search depth
- `valueTypes` (optional, default: ["string", "number", "boolean"]): Types to search
- `maxResults` (optional, default: 50): Maximum results to return
- `includeContext` (optional, default: false): Include surrounding context

**Examples:**
```bash
# Text search
opencode run "search for 'test' in config.json"

# Path-based query
opencode run "search for dependencies in package.json"

# Array wildcard search
opencode run "search for users[*].email in data.json"

# Case sensitive exact match
opencode run "search for 'Production' in config.json case sensitive exact"

# Search specific types
opencode run "search for numbers in metrics.json"
```

## Search Query Patterns

### Text Search
```bash
search for 'error' in logs.json
search for 'version' in package.json
```

### Path Navigation
```bash
search for user.name in profile.json
search for config.database.host in settings.json
```

### Array Operations
```bash
search for items[*].name in catalog.json
search for users[0].email in data.json
search for products[1:5].price in inventory.json
```

### Advanced Options
```bash
search for 'API_KEY' in config.json case sensitive exact
search for 'test' in logs.json max depth 20
search for strings in data.json value types string
```

## Configuration

### Environment Variables

Optional environment variables for customization:

```bash
# Maximum file size for JSON processing (default: 50MB)
JSON_TOOLS_MAX_FILE_SIZE=100

# Maximum search depth for nested structures (default: 10)
JSON_TOOLS_SEARCH_DEPTH=15
```

### Performance Considerations

- Large JSON files are automatically validated against size limits
- Use `includeSampleValues=false` for memory-efficient analysis
- Limit search depth with `maxDepth` parameter for deep structures
- Use type filtering to focus on relevant data types

## Response Format

All tools return structured JSON responses:

### Schema Analysis Response
```json
{
  "success": true,
  "schema": {
    "path": "root",
    "type": "object",
    "depth": 3,
    "keyCount": 5,
    "properties": { /* detailed schema */ }
  },
  "summary": {
    "totalDepth": 3,
    "arrayCount": 2,
    "objectCount": 5,
    "stringCount": 8,
    "numberCount": 3,
    "booleanCount": 1
  },
  "samples": { /* optional sample values */ }
}
```

### Search Response
```json
{
  "success": true,
  "query": "dependencies",
  "totalMatches": 15,
  "returnedMatches": 15,
  "hasMore": false,
  "searchOptions": {
    "caseSensitive": false,
    "exactMatch": false,
    "maxDepth": 10
  },
  "results": [
    {
      "value": "react",
      "path": "dependencies.react",
      "type": "string",
      "depth": 2
    }
  ]
}
```

## Use Cases

### Configuration Analysis
```bash
# Understand complex configuration files
opencode run "analyze schema of webpack.config.json"

# Find specific configuration values
opencode run "search for 'port' in server-config.json"
```

### API Response Exploration
```bash
# Analyze API response structure
opencode run "analyze schema of api-response.json with sample values"

# Extract specific data
opencode run "search for data[*].id in api-response.json"
```

### Data Discovery
```bash
# Explore datasets
opencode run "analyze schema of large-dataset.json"

# Find patterns
opencode run "search for 'error' in logs.json value types string"
```

## Error Handling

The plugin provides comprehensive error handling:

```json
{
  "success": false,
  "error": "File size (120.5MB) exceeds maximum allowed size (50MB)",
  "details": {
    "input": "file: large-data.json"
  }
}
```

Common errors:
- Invalid JSON syntax
- File size exceeded
- File not found
- Invalid search parameters

## Examples

### Real-World Scenarios

1. **Package.json Analysis**
```bash
# Understand project dependencies
opencode run "analyze schema of package.json"

# Find all dependencies
opencode run "search for dependencies in package.json"

# Check scripts
opencode run "search for scripts in package.json"
```

2. **Config File Debugging**
```bash
# Find database configuration
opencode run "search for 'database' in config.json"

# Check for API keys
opencode run "search for 'api' in config.json case sensitive"
```

3. **Data Processing**
```bash
# Extract user emails
opencode run "search for users[*].email in users.json"

# Find status values
opencode run "search for status in data.json"
```

## Contributing

This plugin is part of the OpenPets ecosystem. For issues, feature requests, or contributions:

1. Check existing issues in the repository
2. Follow the OpenPets development patterns
3. Test thoroughly with various JSON structures
4. Update documentation for new features

## License

Part of the OpenPets project. See main project license for details.