@wringer/gunshi 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,7 @@ description:
5
5
  feature works. Load it before you check a change in the running app, run the journey of a feature,
6
6
  or put the verdicts in a PR.'
7
7
  metadata:
8
- wringer-template: 'sha256:97fabc9a9389'
8
+ wringer-template: 'sha256:29e4cfe22eaa'
9
9
  wringer-command: bun verify
10
10
  ---
11
11
 
@@ -13,30 +13,30 @@ metadata:
13
13
 
14
14
  Use `bun verify` to start the app, use each feature your change touches the way a user would, and
15
15
  record a verdict that it works. Put the report in the PR with `bun verify publish`, and hand back
16
- the PR link and each feature you could not verify. The CI gate, `bun verify gate`, fails a PR that
17
- changes a feature with no verdict.
16
+ the PR link and each feature you could not verify. `bun verify gate` fails a PR that changes a
17
+ feature with no verdict in the PR's report.
18
18
 
19
19
  The mistakes that cost the most time:
20
20
 
21
21
  - **Using the app before `doctor` passes.** `bun verify doctor` checks that the app answers and that
22
- each driver works. Until it passes on the run that `up` or `attach` started, any command that
23
- touches the app fails with exit code 3.
22
+ each driver works. A driver is the package behind a command group, such as `http` or `browser`.
23
+ Until `doctor` passes after `up` or `attach`, any command that touches the app fails with exit
24
+ code 3.
24
25
  - **Editing the app's code while `up` runs it.** The next command that touches the app fails with
25
26
  `doctor-required`. Run `bun verify up --restart` and `bun verify doctor`, then the journey again.
26
27
  - **Running `done` before you check the end state.** `done` checks only that one command of the
27
- journey succeeded. Check the result yourself first.
28
- - **Branching on the error message.** Branch on the exit code and `error.code`. The message text can
29
- change in any release.
28
+ journey succeeded.
30
29
 
31
30
  ## Key rules
32
31
 
33
32
  - [Check a change](#check-a-change): for each changed feature, run its journey, check the end state,
34
33
  then `done`.
35
- - [Read the envelope](#read-the-envelope): branch on the exit code and `error.code`.
36
- - [Targets](#targets): check a change on a target that `up` starts.
37
- - [Commands](#commands): `bun verify --help` lists every command.
38
- - [Update a feature file](#update-a-feature-file): fix a broken journey in the same PR, and run
39
- `lint`.
34
+ - [Read the envelope](#read-the-envelope): branch on the exit code and `error.code`, never on the
35
+ message, which can change in any release.
36
+ - [Targets](#targets): check a change on a launch target, which `up` starts.
37
+ - [Commands](#commands): read `--help` before you guess a flag.
38
+ - [Edit the skill and the registry](#edit-the-skill-and-the-registry): fix a broken journey in the
39
+ same PR, map each changed file to a feature, and run `lint`.
40
40
 
41
41
  ## References
42
42
 
@@ -52,11 +52,12 @@ Read a feature's file before you run its journey.
52
52
 
53
53
  ## Check a change
54
54
 
55
- 1. Run `bun verify report`. A feature in `data.report.features` shows `changed: true` when a file
56
- under its `paths` differs from the default branch, committed or not.
57
- 2. Unless your task names another target, start a run on `local`, with the commands in the
58
- [Targets](#targets) table. Expect from `up` or `attach`: `ok: true`, and the app's endpoints in
59
- `data.endpoints`.
55
+ 1. Run `bun verify report`. `changed: true` marks each feature in `data.report.features` with a
56
+ file, committed or not, that matches its `paths` in the
57
+ [registry](#edit-the-skill-and-the-registry) and differs from the default branch.
58
+ 2. Start a run on the target your task names. When it names none, take the first launch target in
59
+ the [Targets](#targets) table. Run the commands in its row. Expect from `up` or `attach`:
60
+ `ok: true`, and the app's endpoints in `data.endpoints`.
60
61
  3. Run `bun verify doctor`. Expect: `data.passed: true`. When a check fails, fix its cause, and run
61
62
  `doctor` again.
62
63
  4. Run the journey from the feature's file in [References](#references). Its first line,
@@ -68,29 +69,31 @@ Read a feature's file before you run its journey.
68
69
  `bun verify doctor` and the journey again.
69
70
  - When your change means to change the end state, fix the feature's file, and run
70
71
  `bun verify lint`. Then run the journey again.
71
- - Otherwise, skip `done` for this feature. List it in your reply with the end state you expected
72
- and the `data` you got.
72
+ - In any other case, such as a `read-only` failure or a bug your change did not cause, skip
73
+ `done` for this feature. List it in your reply with the end state you expected and the `data`
74
+ you got.
73
75
  6. Run `bun verify done` to record a verdict for the feature that `use --feature` set. Expect:
74
76
  `ok: true`. It fails with `check-failed` until a journey command succeeds after `doctor`.
75
77
  7. Repeat steps 4 to 6 for each feature with `changed: true`, and for each feature your task names,
76
78
  in the order of the table in [References](#references). When [Targets](#targets) names a journey
77
79
  to run last, run it last.
78
80
  8. Run `bun verify report --human` to read the report. Expect: `verified` on each changed feature.
79
- After `done`, an edit to a file under a feature's `paths` makes its verdict `stale`; a commit
80
- alone leaves each verdict as it was. Repeat steps 4 to 6 for each stale feature.
81
- 9. Run `bun verify publish`. Expect: `ok: true`, and `data.action` of `created`, `replaced` or
82
- `unchanged`. It writes the report into the description of the branch's open PR. Until you run
83
- `publish`, each verdict from `done` stays in `.wringer/`, where the gate never looks.
81
+ After `done`, an edit to a file that matches a feature's `paths` makes its verdict `stale`; a
82
+ commit alone leaves each verdict as it was. Repeat steps 4 to 6 for each stale feature.
83
+ 9. When the branch has no open PR, open one: without it, `publish` fails and writes nothing. Run
84
+ `bun verify publish`, or `bun verify publish --pr <number>` for another PR. Expect: `ok: true`,
85
+ and `data.action` of `created`, `replaced` or `unchanged`. It writes the report into the PR's
86
+ description, the only report the gate reads.
84
87
  10. End the run: `bun verify down` after `up`, or `bun verify detach` after `attach`.
85
88
 
86
89
  ## Read the envelope
87
90
 
88
91
  Each command prints one JSON envelope as its last line, or text with `--human`. A streaming command,
89
- such as `doctor`, prints JSON event lines before it. Read these fields:
92
+ such as `doctor`, prints JSON event lines before the envelope. Read these fields:
90
93
 
91
94
  - `ok`, then `data` on success, or `error.code`, `error.message` and `error.hint` on failure;
92
95
  - `evidence`: the files the command kept, under `.wringer/`;
93
- - `truncated` and `truncatedPath`: `data` was too large, and the file at `truncatedPath` holds it.
96
+ - `truncatedPath`: the file that holds `data` when it was too large to print.
94
97
 
95
98
  | Exit | `error.code` | Do |
96
99
  | ---- | -------------------- | ------------------------------------------------------------------------------------------------- |
@@ -101,7 +104,7 @@ such as `doctor`, prints JSON event lines before it. Read these fields:
101
104
  | 3 | `doctor-required` | Run the commands in `error.hint`, then run the feature's journey again. |
102
105
  | 3 | `not-running` | Start the run, as step 2 says. |
103
106
  | 3 | `target-not-allowed` | Follow `error.hint`. |
104
- | 4 | `environment` | Read `error.message`, fix the problem on this machine, such as a missing browser, and retry. |
107
+ | 4 | `environment` | Read `error.message` and `error.hint`, fix the problem, such as a missing browser, and retry. |
105
108
  | 4 | `internal` | Report the command and `error.message`: the CLI has a bug. |
106
109
  | 5 | `timeout` | Retry once with twice the timeout; the default is `--timeout-ms=120000`. Report a second timeout. |
107
110
 
@@ -109,12 +112,12 @@ such as `doctor`, prints JSON event lines before it. Read these fields:
109
112
 
110
113
  Start a launch target's app with `bun verify up`, and stop it with `bun verify down`. Connect to an
111
114
  attach target, an app that runs apart from `bun verify`, with `bun verify attach`.
112
- `bun verify detach` leaves it running. Your edits never reach an attach target's app, so check a
113
- change on a launch target.
115
+ `bun verify detach` leaves it running. A run lasts from `up` or `attach` to `down` or `detach`. Your
116
+ edits never reach an attach target's app, so check a change on a launch target.
114
117
 
115
118
  Run `bun verify use --target <target>` to point every later command at a target. `use` saves the
116
- choice in this worktree's `.wringer/`, so it holds across shells and sessions. `--target` on one
117
- command points that command alone.
119
+ choice in this worktree's `.wringer/`, for every shell and session. `--target` on one command points
120
+ that command alone. A command with neither runs on the registry's first target, so run `use` first.
118
121
 
119
122
  <!-- repo: targets -->
120
123
 
@@ -142,12 +145,13 @@ only the name of a group, such as `action`: run `bun verify <group> --help` for
142
145
 
143
146
  <!-- /repo -->
144
147
 
145
- ## Update a feature file
148
+ ## Edit the skill and the registry
146
149
 
147
150
  <!-- repo: registry -->
148
151
 
149
152
  The registry, `scripts/verify/create-verify-registry.ts`, declares the targets, actions, commands,
150
- doctor checks and features, with each feature's `paths`.
153
+ doctor checks and features, with each feature's `paths`. CI runs `bun verify lint` and
154
+ `bun verify gate` on each PR.
151
155
 
152
156
  <!-- /repo -->
153
157
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wringer/gunshi",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
4
4
  "description": "The gunshi adapter for wringer: turns a wringer registry into a CLI",
5
5
  "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/gunshi#readme",
6
6
  "bugs": "https://github.com/zgeoff/wringer/issues",