@wringer/gunshi 0.3.2 → 0.3.4

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:bc652053a9dc'
9
9
  wringer-command: bun verify
10
10
  ---
11
11
 
@@ -13,30 +13,31 @@ 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. Leave `bun verify gate` to CI: it reads the
17
+ report from the PR description, and fails a PR that changes a feature with no verdict there.
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 a package, such as `@wringer/http`, that adds a group of commands,
23
+ such as `bun verify http request`. Until `doctor` passes after `bun verify up` or
24
+ `bun verify attach`, any command that touches the app fails with exit 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, a target whose app `bun verify up` starts
37
+ from your worktree.
38
+ - [Commands](#commands): read `--help` before you guess a flag.
39
+ - [Edit the skill and the registry](#edit-the-skill-and-the-registry): fix a broken journey in the
40
+ same PR, map each changed file in the registry, and run `lint`.
40
41
 
41
42
  ## References
42
43
 
@@ -52,69 +53,76 @@ Read a feature's file before you run its journey.
52
53
 
53
54
  ## Check a change
54
55
 
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`.
56
+ 1. Run `bun verify report`. In `data.report.features`, a feature shows `changed: true` when a file
57
+ that matches its `paths` in the [registry](#edit-the-skill-and-the-registry) differs from the
58
+ default branch, committed or not.
59
+ 2. Pick the target your task names. When it names none, take the first launch target in the
60
+ [Targets](#targets) table. Run the commands in its row. `up` or `attach` starts a run, which
61
+ lasts until `down` or `detach`. Expect from `up` or `attach`: `ok: true`, and the app's endpoints
62
+ in `data.endpoints`.
60
63
  3. Run `bun verify doctor`. Expect: `data.passed: true`. When a check fails, fix its cause, and run
61
64
  `doctor` again.
62
65
  4. Run the journey from the feature's file in [References](#references). Its first line,
63
66
  `use --feature`, records each later command under that feature, and leaves the target as it is.
64
- Expect: each command exits 0.
67
+ Expect: each command exits 0. When one fails, do what its row in
68
+ [Read the envelope](#read-the-envelope) says.
65
69
  5. Compare the app with the feature's end state:
66
70
  - When it matches, and no command failed with `read-only`, go on to step 6.
67
71
  - When your change broke the feature, fix the app's code. Then run `bun verify up --restart`,
68
72
  `bun verify doctor` and the journey again.
69
73
  - When your change means to change the end state, fix the feature's file, and run
70
74
  `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.
73
- 6. Run `bun verify done` to record a verdict for the feature that `use --feature` set. Expect:
75
+ - In any other case, such as a `read-only` failure or a bug your change did not cause, skip
76
+ `done` for this feature. List it in your reply with the end state you expected and the `data`
77
+ you got.
78
+ 6. Finish each edit to a file that matches the feature's `paths` before you run `done`. An edit
79
+ after `done` makes the feature's verdict `stale`. A commit alone leaves the verdict as it was.
80
+ Run `bun verify done` to record a verdict for the feature that `use --feature` set. Expect:
74
81
  `ok: true`. It fails with `check-failed` until a journey command succeeds after `doctor`.
75
82
  7. Repeat steps 4 to 6 for each feature with `changed: true`, and for each feature your task names,
76
- in the order of the table in [References](#references). When [Targets](#targets) names a journey
77
- to run last, run it last.
78
- 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.
83
+ in the order of the table in [References](#references). When the [Targets](#targets) section says
84
+ to run a feature's journey last, run it after every other journey.
85
+ 8. Run `bun verify report --human` to read the report. Expect: `verified` on each changed feature
86
+ you did not skip in step 5. Repeat steps 4 to 6 for each `stale` feature.
87
+ 9. Push the branch, and open a PR for it when none is open. Without an open PR, `publish` fails and
88
+ writes nothing. Run `bun verify publish`, even when you skipped a feature. To write to a PR other
89
+ than the branch's own, add `--pr <number>`. Expect: `ok: true`, and `data.action` of `created`,
90
+ `replaced` or `unchanged`. It writes the report into the PR's description, the only report the
91
+ gate reads.
84
92
  10. End the run: `bun verify down` after `up`, or `bun verify detach` after `attach`.
85
93
 
86
94
  ## Read the envelope
87
95
 
88
96
  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:
97
+ such as `doctor`, prints JSON event lines before the envelope. Read these fields:
90
98
 
91
99
  - `ok`, then `data` on success, or `error.code`, `error.message` and `error.hint` on failure;
92
100
  - `evidence`: the files the command kept, under `.wringer/`;
93
- - `truncated` and `truncatedPath`: `data` was too large, and the file at `truncatedPath` holds it.
94
-
95
- | Exit | `error.code` | Do |
96
- | ---- | -------------------- | ------------------------------------------------------------------------------------------------- |
97
- | 0 | none | Go on. |
98
- | 1 | `check-failed` | Read the evidence. When `done` failed, run the journey again; else go on as step 5 says. |
99
- | 2 | `usage` | Fix the command; `--help` shows its flags. |
100
- | 3 | `read-only` | Leave the write undone, skip `done` for the feature, and list the write in your reply. |
101
- | 3 | `doctor-required` | Run the commands in `error.hint`, then run the feature's journey again. |
102
- | 3 | `not-running` | Start the run, as step 2 says. |
103
- | 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. |
105
- | 4 | `internal` | Report the command and `error.message`: the CLI has a bug. |
106
- | 5 | `timeout` | Retry once with twice the timeout; the default is `--timeout-ms=120000`. Report a second timeout. |
101
+ - `truncatedPath`: the file that holds `data` when it was too large to print.
102
+
103
+ | Exit | `error.code` | Do |
104
+ | ---- | -------------------- | --------------------------------------------------------------------------------------------------- |
105
+ | 0 | none | Go on. |
106
+ | 1 | `check-failed` | Read the evidence. When `done` failed, run the journey again. Else compare the app, as step 5 says. |
107
+ | 2 | `usage` | Fix the command; `--help` shows its flags. |
108
+ | 3 | `read-only` | Leave the write undone, skip `done` for the feature, and list the write in your reply. |
109
+ | 3 | `doctor-required` | Run the commands in `error.hint`, then run the feature's journey again. |
110
+ | 3 | `not-running` | Start the run, as step 2 says. |
111
+ | 3 | `target-not-allowed` | Follow `error.hint`. |
112
+ | 4 | `environment` | Read `error.message` and `error.hint`, fix the problem, such as a missing browser, and retry. |
113
+ | 4 | `internal` | Report the command and `error.message`: the CLI has a bug. |
114
+ | 5 | `timeout` | Retry once with twice the timeout; the default is `--timeout-ms=120000`. Report a second timeout. |
107
115
 
108
116
  ## Targets
109
117
 
110
118
  Start a launch target's app with `bun verify up`, and stop it with `bun verify down`. Connect to an
111
- attach target, an app that runs apart from `bun verify`, with `bun verify attach`.
119
+ attach target, a target whose app runs apart from `bun verify`, with `bun verify attach`.
112
120
  `bun verify detach` leaves it running. Your edits never reach an attach target's app, so check a
113
121
  change on a launch target.
114
122
 
115
123
  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.
124
+ choice in this worktree's `.wringer/`, for every shell and session. `--target` on one command points
125
+ that command alone. A command with neither runs on the registry's first target, so run `use` first.
118
126
 
119
127
  <!-- repo: targets -->
120
128
 
@@ -128,9 +136,10 @@ command points that command alone.
128
136
  ## Commands
129
137
 
130
138
  Run `bun verify --help` for the list, with each command marked `[read]` or `[write]`. A read-only
131
- target refuses each `[write]` command that writes app data. `up` and `down` are `[read]`, but start
132
- and stop the app. Run `bun verify <command> --help` for a command's flags. The top-level list shows
133
- only the name of a group, such as `action`: run `bun verify <group> --help` for its commands.
139
+ target refuses each `[write]` command except `publish`, which writes no app data. `up` and `down`
140
+ are `[read]`, but start and stop the app. Run `bun verify <command> --help` for a command's flags.
141
+ The top-level list shows only the name of a group, such as `action`: run `bun verify <group> --help`
142
+ for its commands.
134
143
 
135
144
  - Write a negative number with `=`, as in `--offset=-5`.
136
145
  - Pass an object as JSON text, as in `--filter '{"shelf":"top"}'`.
@@ -142,12 +151,13 @@ only the name of a group, such as `action`: run `bun verify <group> --help` for
142
151
 
143
152
  <!-- /repo -->
144
153
 
145
- ## Update a feature file
154
+ ## Edit the skill and the registry
146
155
 
147
156
  <!-- repo: registry -->
148
157
 
149
158
  The registry, `scripts/verify/create-verify-registry.ts`, declares the targets, actions, commands,
150
- doctor checks and features, with each feature's `paths`.
159
+ doctor checks and features, with each feature's `paths`. CI runs `bun verify lint` and
160
+ `bun verify gate` on each PR.
151
161
 
152
162
  <!-- /repo -->
153
163
 
@@ -162,9 +172,11 @@ doctor checks and features, with each feature's `paths`.
162
172
  `bun verify features --markdown`.
163
173
  - Leave `metadata.wringer-template` as it is. When `lint` fails with check `template`, run
164
174
  `bun verify guide maintain`, and follow its steps to upgrade the template.
165
- - Make each changed file match a feature's `paths` or a glob in the registry's `.ignore` list. The
166
- gate fails on a changed file that matches neither. `bun verify features` lists each feature's
167
- `paths`.
175
+ - Make each changed file match a feature's `paths`, a shared glob or a glob in the ignore list. The
176
+ registry sets the shared globs with `.shared()` and the ignore list with `.ignore()`. The gate
177
+ fails on a changed file that matches none of them. Add a file the running app never reads, such as
178
+ a test, to the ignore list. `bun verify features` lists each feature's `paths`, the shared globs
179
+ in `data.shared` and the ignore list in `data.ignore`.
168
180
  - After you change this skill, a feature file or the registry, run `bun verify lint`, and fix each
169
181
  failure it reports.
170
182
 
@@ -1,7 +1,8 @@
1
1
  # add-item
2
2
 
3
- A user adds an item to the pantry on the `/pantry` page, by typing a name and pressing Add. The
4
- journey adds the item through the API that the form calls.
3
+ Check that an item added to the pantry reaches the item list. On the `/pantry` page, a user types a
4
+ name and presses Add, and the form sends it to the items API. The journey calls that API, as the
5
+ form does, so it checks a change to the API. It never loads the page.
5
6
 
6
7
  ## Journey
7
8
 
@@ -10,11 +11,13 @@ bun verify use --feature add-item
10
11
  bun verify items count
11
12
  bun verify action add-item --name Oats
12
13
  bun verify items count
13
- bun verify http request --path /api/items
14
+ bun verify http request --method GET --path /api/items
14
15
  ```
15
16
 
16
17
  ## End state
17
18
 
18
- - The `data.count` of the second `items count` is one more than the first.
19
- - The `data.json` of `http request` lists an item named `Oats`. An earlier run may have added one
20
- too. Only the count proves this run added it.
19
+ Both must hold:
20
+
21
+ - The second `items count` prints a `data.count` one more than the first `items count`.
22
+ - The `data.json` of `http request` lists an item named `Oats`. An earlier journey may have left an
23
+ `Oats` item, so this check alone proves nothing.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wringer/gunshi",
3
- "version": "0.3.2",
3
+ "version": "0.3.4",
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",