wavepeek 1.0.1

Command-line tool for RTL waveform inspection with deterministic machine-friendly output.
Documentation 
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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

---
id: reference/machine-output
title: Machine Output Contract
description: Stable stdout, stderr, JSON envelope, diagnostic, schema, fatal-error, and exit-code behavior.
section: reference
see_also:
  - reference/command-model
  - commands/schema
  - commands/skill
---
# Machine Output Contract

This document is normative for stdout, stderr, JSON-mode behavior, schema linkage, diagnostics, and exit codes.

## 1. Stdout and Stderr Responsibilities

On success, a command writes its main payload to stdout.

- In human-readable mode, non-fatal diagnostics are written to stderr as plain text.
- In `--json` mode, non-fatal diagnostics are carried inside the JSON payload.
- In `schema` mode, stdout contains exactly one JSON Schema document.

On failure, stdout is empty. Process-level failures are reported on stderr only.

## 2. JSON Envelope for Stable `--json` Commands

When a stable JSON-producing command succeeds under `--json`, it emits one JSON object with this shape:

```json
{
  "$schema": "https://kleverhq.github.io/wavepeek/wavepeek_v<major>.json",
  "command": "<command>",
  "data": {},
  "diagnostics": []
}
```

The semantics of the envelope fields are:

- `$schema` is serialized literally as `$schema` and points at the canonical schema artifact for the running wavepeek major version.
- `command` identifies the executed subcommand and disambiguates the shape of `data`.
- `data` carries the command payload. Depending on the command contract, it may be an object or an array.
- `diagnostics` is an array of typed diagnostic objects in deterministic order.

A diagnostic object has `kind`, `message`, and sometimes `code`:

```json
{
  "kind": "warning",
  "code": "WPK-W0002",
  "message": "truncated output to 1 entries (use --max to increase limit)"
}
```

`kind` is one of `info`, `warning`, or `error`. `warning` and `error` diagnostics always include a stable `code` matching `WPK-W####` or `WPK-E####`. `info` diagnostics omit `code`.

The exact JSON shapes for every command are defined by the current major artifact such as `schema/wavepeek_v1.json` and by `wavepeek schema`.

The stable JSON-producing commands currently include the waveform-inspection commands plus `docs topics --json` and `docs search --json`. Human-only helper surfaces such as `skill` and human-only docs subcommands such as `docs show` and `docs export` do not silently change output modes; unsupported `--json` combinations fail as argument errors and leave stdout empty.

## 3. `schema` Command Behavior

`wavepeek schema` is the authority for the machine-readable output contract.

Its behavior is special and fixed:

- it accepts no waveform input,
- it accepts no command-specific flags or positional arguments,
- it writes exactly one JSON Schema document to stdout,
- it does not wrap that document in the normal command envelope, and
- its output bytes match the canonical artifact for the running major version, such as `schema/wavepeek_v1.json`.

## 4. Diagnostic Behavior

Diagnostics do not change the exit code. A command can therefore succeed with diagnostics.

Common diagnostic cases include truncated output, explicitly disabled limits, and semantically empty-but-valid queries such as a selected range with no matching signal changes.

Diagnostic transport depends on the output mode:

- human-readable mode sends diagnostics to stderr,
- `--json` mode stores diagnostics in the envelope's `diagnostics` array.

Human-readable diagnostics use these formats:

```text
info: <message>
warning[WPK-W0002]: <message>
error[WPK-E0001]: <message>
```

## 5. Fatal Error Format and Exit Codes

Process-level failures are fail-fast and machine-parseable. The stderr format is:

```text
fatal: <category>: <message>
```

Representative categories include `args`, `file`, `scope`, `signal`, and `expr`.

Exit codes are stable at the process level:

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | User-facing failure such as bad arguments, missing scopes/signals, or invalid expressions |
| `2` | File-level failure such as open, parse, or unsupported-format failures |

Fatal errors are never wrapped in the JSON success envelope. Even in `--json` mode, stdout stays empty on failure and stderr carries the formatted fatal line.

## 6. Human Output Flexibility

Human-readable output is part of the user experience, but it is intentionally less rigid than the machine contract. Commands may improve human formatting over time as long as they preserve the semantic guarantees documented in `command-model` and the stricter cases called out by command-specific help or tests.