fmtview 0.1.3

Fast terminal formatter and viewer for JSON, JSONL, XML-compatible markup, and formatted diffs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# AGENTS.md

Principles for agents contributing to this repository.

## Core Principles

1. **KISS**
   - Prefer the simplest solution that satisfies the current CLI behavior.
   - Avoid speculative plugin systems, background daemons, or broad abstractions.
   - Keep modules small enough to read in one pass.

2. **Large-file behavior is a product requirement**
   - Do not load formatted output into memory for terminal viewing.
   - Prefer streaming parsers and temporary files with line indexes.
   - If a feature requires whole-document parsing, make that tradeoff explicit in the CLI or docs.

3. **Conventional Commits with real bodies**
   - Use Conventional Commits for every commit.
   - Include a body that explains what changed and why.

## Navigation

Use README for user-facing behavior. Use docs for maintainer workflows and
durable project decisions.

Keep this file coarse-grained. Do not mirror every implementation detail here.

### Read these docs first

- `README.md`
- `docs/INDEX.md`

### Read these docs when the task matches

- Release, packaging, crates.io, npm, GitHub Releases, or version tags:
  - Read `docs/releasing.md`

## Source Map

- `src/main.rs` - CLI argument parsing and command routing.
- `src/input.rs` - file, stdin, and literal input materialization.
- `src/format.rs` - JSON, JSONL, XML formatting and auto-detection.
- `src/diff.rs` - formatted unified diff generation.
- `src/line_index.rs` - temp-file line offset indexing for large outputs.
- `src/viewer.rs` - interactive terminal viewer.
- `tests/` - CLI-level behavior tests.

## Engineering Rules

- Keep stdout output valid and scriptable.
- Keep interactive behavior behind TTY detection.
- Preserve JSON string values. The viewer may highlight embedded XML, but formatted output must not rewrite string contents.
- Update `README.md` when CLI flags, install steps, or user-visible behavior changes.
- Update `docs/releasing.md` when release, packaging, npm, crates.io, or artifact policy changes.
- Prefer Linux-first behavior, but avoid unnecessary non-portable code when portable Rust is simple.

## Verification Requirements

- Run `cargo fmt`.
- Run `cargo test`.
- Run `cargo clippy --all-targets -- -D warnings` when Clippy is available.
- For TUI changes, run the built CLI under a real PTY, for example with `script`, and verify scroll/quit keys.