@wringer/gunshi 0.3.3 → 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:
|
|
8
|
+
wringer-template: 'sha256:bc652053a9dc'
|
|
9
9
|
wringer-command: bun verify
|
|
10
10
|
---
|
|
11
11
|
|
|
@@ -13,15 +13,15 @@ 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. `bun verify gate`
|
|
17
|
-
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. A driver is
|
|
23
|
-
Until `doctor` passes after `up` or
|
|
24
|
-
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.
|
|
25
25
|
- **Editing the app's code while `up` runs it.** The next command that touches the app fails with
|
|
26
26
|
`doctor-required`. Run `bun verify up --restart` and `bun verify doctor`, then the journey again.
|
|
27
27
|
- **Running `done` before you check the end state.** `done` checks only that one command of the
|
|
@@ -33,10 +33,11 @@ The mistakes that cost the most time:
|
|
|
33
33
|
then `done`.
|
|
34
34
|
- [Read the envelope](#read-the-envelope): branch on the exit code and `error.code`, never on the
|
|
35
35
|
message, which can change in any release.
|
|
36
|
-
- [Targets](#targets): check a change on a launch target,
|
|
36
|
+
- [Targets](#targets): check a change on a launch target, a target whose app `bun verify up` starts
|
|
37
|
+
from your worktree.
|
|
37
38
|
- [Commands](#commands): read `--help` before you guess a flag.
|
|
38
39
|
- [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
|
|
40
|
+
same PR, map each changed file in the registry, and run `lint`.
|
|
40
41
|
|
|
41
42
|
## References
|
|
42
43
|
|
|
@@ -52,17 +53,19 @@ 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`.
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
2.
|
|
59
|
-
|
|
60
|
-
`ok: true`, and the app's 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`.
|
|
61
63
|
3. Run `bun verify doctor`. Expect: `data.passed: true`. When a check fails, fix its cause, and run
|
|
62
64
|
`doctor` again.
|
|
63
65
|
4. Run the journey from the feature's file in [References](#references). Its first line,
|
|
64
66
|
`use --feature`, records each later command under that feature, and leaves the target as it is.
|
|
65
|
-
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.
|
|
66
69
|
5. Compare the app with the feature's end state:
|
|
67
70
|
- When it matches, and no command failed with `read-only`, go on to step 6.
|
|
68
71
|
- When your change broke the feature, fix the app's code. Then run `bun verify up --restart`,
|
|
@@ -72,18 +75,20 @@ Read a feature's file before you run its journey.
|
|
|
72
75
|
- In any other case, such as a `read-only` failure or a bug your change did not cause, skip
|
|
73
76
|
`done` for this feature. List it in your reply with the end state you expected and the `data`
|
|
74
77
|
you got.
|
|
75
|
-
6.
|
|
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:
|
|
76
81
|
`ok: true`. It fails with `check-failed` until a journey command succeeds after `doctor`.
|
|
77
82
|
7. Repeat steps 4 to 6 for each feature with `changed: true`, and for each feature your task names,
|
|
78
|
-
in the order of the table in [References](#references). When [Targets](#targets)
|
|
79
|
-
to run last, run it
|
|
80
|
-
8. Run `bun verify report --human` to read the report. Expect: `verified` on each changed feature
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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.
|
|
87
92
|
10. End the run: `bun verify down` after `up`, or `bun verify detach` after `attach`.
|
|
88
93
|
|
|
89
94
|
## Read the envelope
|
|
@@ -95,25 +100,25 @@ such as `doctor`, prints JSON event lines before the envelope. Read these fields
|
|
|
95
100
|
- `evidence`: the files the command kept, under `.wringer/`;
|
|
96
101
|
- `truncatedPath`: the file that holds `data` when it was too large to print.
|
|
97
102
|
|
|
98
|
-
| Exit | `error.code` | Do
|
|
99
|
-
| ---- | -------------------- |
|
|
100
|
-
| 0 | none | Go on.
|
|
101
|
-
| 1 | `check-failed` | Read the evidence. When `done` failed, run the journey again
|
|
102
|
-
| 2 | `usage` | Fix the command; `--help` shows its flags.
|
|
103
|
-
| 3 | `read-only` | Leave the write undone, skip `done` for the feature, and list the write in your reply.
|
|
104
|
-
| 3 | `doctor-required` | Run the commands in `error.hint`, then run the feature's journey again.
|
|
105
|
-
| 3 | `not-running` | Start the run, as step 2 says.
|
|
106
|
-
| 3 | `target-not-allowed` | Follow `error.hint`.
|
|
107
|
-
| 4 | `environment` | Read `error.message` and `error.hint`, fix the problem, such as a missing browser, and retry.
|
|
108
|
-
| 4 | `internal` | Report the command and `error.message`: the CLI has a bug.
|
|
109
|
-
| 5 | `timeout` | Retry once with twice the timeout; the default is `--timeout-ms=120000`. Report a second timeout.
|
|
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. |
|
|
110
115
|
|
|
111
116
|
## Targets
|
|
112
117
|
|
|
113
118
|
Start a launch target's app with `bun verify up`, and stop it with `bun verify down`. Connect to an
|
|
114
|
-
attach target,
|
|
115
|
-
`bun verify detach` leaves it running.
|
|
116
|
-
|
|
119
|
+
attach target, a target whose app runs apart from `bun verify`, with `bun verify attach`.
|
|
120
|
+
`bun verify detach` leaves it running. Your edits never reach an attach target's app, so check a
|
|
121
|
+
change on a launch target.
|
|
117
122
|
|
|
118
123
|
Run `bun verify use --target <target>` to point every later command at a target. `use` saves the
|
|
119
124
|
choice in this worktree's `.wringer/`, for every shell and session. `--target` on one command points
|
|
@@ -131,9 +136,10 @@ that command alone. A command with neither runs on the registry's first target,
|
|
|
131
136
|
## Commands
|
|
132
137
|
|
|
133
138
|
Run `bun verify --help` for the list, with each command marked `[read]` or `[write]`. A read-only
|
|
134
|
-
target refuses each `[write]` command
|
|
135
|
-
and stop the app. Run `bun verify <command> --help` for a command's flags.
|
|
136
|
-
only the name of a group, such as `action`: run `bun verify <group> --help`
|
|
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.
|
|
137
143
|
|
|
138
144
|
- Write a negative number with `=`, as in `--offset=-5`.
|
|
139
145
|
- Pass an object as JSON text, as in `--filter '{"shelf":"top"}'`.
|
|
@@ -166,9 +172,11 @@ doctor checks and features, with each feature's `paths`. CI runs `bun verify lin
|
|
|
166
172
|
`bun verify features --markdown`.
|
|
167
173
|
- Leave `metadata.wringer-template` as it is. When `lint` fails with check `template`, run
|
|
168
174
|
`bun verify guide maintain`, and follow its steps to upgrade the template.
|
|
169
|
-
- Make each changed file match a feature's `paths
|
|
170
|
-
|
|
171
|
-
|
|
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`.
|
|
172
180
|
- After you change this skill, a feature file or the registry, run `bun verify lint`, and fix each
|
|
173
181
|
failure it reports.
|
|
174
182
|
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# add-item
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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.
|
|
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",
|