nils-api-websocket 0.4.1

CLI crate for nils-api-websocket in the nils-cli workspace.
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

# WebSocket CLI Contract v1

## Commands
`api-websocket` supports:
- `call`
- `history`
- `report`
- `report-from-cmd`

Default command behavior:
- bare positional request path is treated as `call`.

## Exit codes
- `0`: success
- `1`: operational/validation failure
- `3`: history file exists but contains no records (`history`)

## Stdout/stderr behavior
- `call` (text mode): stdout prints the last received message.
- `history` (text mode): stdout prints selected history records.
- `report`/`report-from-cmd`: stdout prints generated report path.
- stderr is used for human-readable diagnostics in text mode.

## JSON mode
- Explicit only: `--format json`
- Supported commands: `call`, `history`
- Human-readable mode remains default.

## JSON envelope
Guideline reference:
- `docs/specs/cli-service-json-contract-guideline-v1.md`

### `call` success
```json
{
  "schema_version": "cli.api-websocket.call.v1",
  "command": "api-websocket call",
  "ok": true,
  "result": {
    "target": "ws://127.0.0.1:9001/ws",
    "last_received": "{\"ok\":true}",
    "transcript": []
  }
}
```

### `call` failure
```json
{
  "schema_version": "cli.api-websocket.call.v1",
  "command": "api-websocket call",
  "ok": false,
  "error": {
    "code": "request_not_found",
    "message": "Request file not found: ..."
  }
}
```

### `history` success
```json
{
  "schema_version": "cli.api-websocket.history.v1",
  "command": "api-websocket history",
  "ok": true,
  "result": {
    "history_file": ".../.ws_history",
    "count": 1,
    "records": ["..."]
  }
}
```

### `history` failure
```json
{
  "schema_version": "cli.api-websocket.history.v1",
  "command": "api-websocket history",
  "ok": false,
  "error": {
    "code": "history_not_found",
    "message": "History file not found: ..."
  }
}
```

## Stable error codes

### `call`
- `request_not_found`
- `request_parse_error`
- `setup_resolve_error`
- `endpoint_resolve_error`
- `auth_resolve_error`
- `jwt_validation_error`
- `websocket_execute_error`
- `expectation_failed`

### `history`
- `history_resolve_error`
- `history_not_found`
- `history_read_error`
- `history_empty`

## Secret handling
- JSON output must not include bearer token material.
- Tokens are never emitted in `result` payloads.
- history command snippets mask token values (`REDACTED`) in suite artifacts.