jsont TUI JSON Viewer

A Terminal User Interface (TUI) JSON viewer built with React and Ink. Reads JSON from stdin or files and displays it in interactive formats including tree view, collapsible view, and schema view with jq and JSONata query capabilities.

Architecture

The codebase follows **clean architecture** with feature-driven organization:

Layer Structure

- `AppService` orchestrates application lifecycle

- Utilities: terminal management, stdin processing, error handling, LRU caching, CLI parsing

- Data converters: SQL, XML, YAML, CSV, JSON Schema

- YAML configuration system with hot reloading and validation

State Management

Keyboard Input Architecture

Key Commands

Development

Testing

Code Quality

Usage

```bash

echo '{"key": "value"}' | npm run dev

cat file.json | npm run dev

npm run dev path/to/file.json

```

Technical Stack

Development Guidelines

Import Standards

**Always use extensionless imports** for TypeScript files.

**Path Aliases**:

**Import Order**: external dependencies → path aliases → relative imports

Example:

```typescript

import { Box, Text } from "ink";

import type { JsonValue } from "@core/types/index";

import { TreeView } from "@features/tree/components/TreeView";

import { useUI } from "@store/hooks/useUI";

import { formatData } from "./utils/formatter";

```

File Organization

Error Handling

TypeScript Configuration

Features

Navigation

Interactive Settings TUI

Configuration

Data Export

Performance Optimization

CI/CD Optimization

Instructions for AI Agent

When working with this codebase:

1. **Respect Clean Architecture**: Keep core utilities, features, and components separated. Core layer should not depend on features.

2. **Use Correct Import Paths**: Always use extensionless imports and supported path aliases (`@/*`, `@core/*`, `@features/*`). Do not use `@store/*`, `@components/*`, `@hooks/*` in production code.

3. **Follow Error Handling Patterns**: Use `neverthrow` Result types. Never throw exceptions in utility functions. Return `Result<T, E>` for operations that can fail.

4. **Co-locate Tests**: Place `.spec.ts` files alongside implementation. Ensure tests cover edge cases and error paths.

5. **Maintain State Patterns**: Use Jotai atoms for global state. Define atoms in `src/store/atoms/`, expose via typed hooks in `src/store/hooks/`.

6. **Keyboard Input Handling**: Register keyboard handlers via callback props to KeyboardManager. Do not use `useInput` directly in feature components.

7. **Configuration Changes**: Update Zod schema in `src/core/config/` when adding configuration options. Ensure default values are provided.

8. **Performance Considerations**: Use LRU caching for expensive operations. Profile large dataset handling. Keep CI test exclusions in mind for memory-intensive tests.

9. **Code Quality**: Run `npm run check:write` before committing. Biome enforces double quotes, 2-space indentation, and import organization.

10. **Export Features**: Add new export formats to `src/core/utils/dataConverters/`. Update export handlers in `src/hooks/handlers/exportHandler.ts`.

11. **Testing**: Run `npm run test:coverage` to ensure adequate coverage. Use `npm run test:ci` to validate CI behavior locally.

12. **Documentation**: Update CLAUDE.md when adding new features, changing architecture, or modifying configuration structure.