@wringer/gunshi 0.1.1 → 0.2.0
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.
- package/package.json +4 -4
- package/skills/wringer/SKILL.md +24 -19
- package/skills/wringer/references/create.md +12 -3
- package/skills/wringer/references/maintain.md +8 -4
- package/skills/wringer/references/prove.md +5 -3
- package/skills/wringer/template/verify/SKILL.md +3 -2
- package/skills/wringer/template/verify-registry.ts +1 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wringer/gunshi",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
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",
|
|
@@ -42,12 +42,12 @@
|
|
|
42
42
|
"zod": "4.6.7"
|
|
43
43
|
},
|
|
44
44
|
"devDependencies": {
|
|
45
|
-
"@wringer/core": "0.
|
|
46
|
-
"@wringer/http": "0.1.
|
|
45
|
+
"@wringer/core": "0.2.0",
|
|
46
|
+
"@wringer/http": "0.1.2",
|
|
47
47
|
"@zgeoff/testing": "0.3.0"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
|
-
"@wringer/core": "0.
|
|
50
|
+
"@wringer/core": "0.2.0"
|
|
51
51
|
},
|
|
52
52
|
"engines": {
|
|
53
53
|
"bun": ">=1.3"
|
package/skills/wringer/SKILL.md
CHANGED
|
@@ -13,23 +13,24 @@ these in the repo:
|
|
|
13
13
|
|
|
14
14
|
- a verify CLI on the `@wringer/*` packages, which an agent runs as `bun verify <command>`;
|
|
15
15
|
- its registry: the code that declares the targets, the drivers, the actions, the doctor checks and
|
|
16
|
-
the features,
|
|
16
|
+
the features, with each feature's `paths` globs, and the ignore list, set with `.ignore`: the
|
|
17
|
+
globs of the files the running app never reads;
|
|
17
18
|
- a `verify` skill, with a feature map in its `references/feature-map.md` that gives each feature's
|
|
18
19
|
journey.
|
|
19
20
|
|
|
20
21
|
These terms hold across this skill and its references:
|
|
21
22
|
|
|
22
|
-
| Term | Meaning
|
|
23
|
-
| --------- |
|
|
24
|
-
| target | where the app runs: `local`, which the CLI starts, or an instance it attaches to
|
|
25
|
-
| read-only | a target's access that refuses each write with exit code 3
|
|
26
|
-
| driver | a package that adds a group of commands, such as `@wringer/http` and `http request`
|
|
27
|
-
| action | a named step of the repo's own, run as `bun verify action <name>`
|
|
28
|
-
| doctor | `bun verify doctor`: the checks that must pass before any command that touches the app
|
|
29
|
-
| journey | the `bun verify` commands that use one feature, and the end state that shows it works
|
|
30
|
-
| verdict | what `bun verify done` records: the feature works on the current code
|
|
31
|
-
| gate | `bun verify gate` in CI: it fails a PR
|
|
32
|
-
| report | the output of `bun verify report --human`, which the PR body holds for the gate
|
|
23
|
+
| Term | Meaning |
|
|
24
|
+
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
25
|
+
| target | where the app runs: `local`, which the CLI starts, or an instance it attaches to |
|
|
26
|
+
| read-only | a target's access that refuses each write with exit code 3 |
|
|
27
|
+
| driver | a package that adds a group of commands, such as `@wringer/http` and `http request` |
|
|
28
|
+
| action | a named step of the repo's own, run as `bun verify action <name>` |
|
|
29
|
+
| doctor | `bun verify doctor`: the checks that must pass before any command that touches the app |
|
|
30
|
+
| journey | the `bun verify` commands that use one feature, and the end state that shows it works |
|
|
31
|
+
| verdict | what `bun verify done` records: the feature works on the current code |
|
|
32
|
+
| gate | `bun verify gate` in CI: it fails a PR on a changed feature without a verdict, and on a changed file outside every `paths` glob and the ignore list |
|
|
33
|
+
| report | the output of `bun verify report --human`, which the PR body holds for the gate |
|
|
33
34
|
|
|
34
35
|
Then prove them, and wire the checks that keep them true. Hand back the PR that adds them, with the
|
|
35
36
|
proof in its description. The mistakes that cost the most:
|
|
@@ -38,8 +39,8 @@ proof in its description. The mistakes that cost the most:
|
|
|
38
39
|
only the `verify` skill. Run a subagent with none of your context to show that the skill works.
|
|
39
40
|
- **Copying commands into the `verify` skill.** The CLI lists its own commands in `--help`, and a
|
|
40
41
|
copy goes stale. Point at `--help`, and write only what the help can't say.
|
|
41
|
-
- **A `paths` glob that matches no file.**
|
|
42
|
-
|
|
42
|
+
- **A `paths` glob that matches no file.** The files it should cover then fail the gate as unmapped,
|
|
43
|
+
unless another feature's glob covers them. Run `bun verify lint` to find one.
|
|
43
44
|
- **Writing a repo's own choices outside the `<!-- repo -->` blocks of the `verify` skill.** An
|
|
44
45
|
upgrade of the template replaces every line outside them. Put each choice, such as where an agent
|
|
45
46
|
reports a refused write, in a block or in the repo's code.
|
|
@@ -49,8 +50,8 @@ proof in its description. The mistakes that cost the most:
|
|
|
49
50
|
- [Install the skill](#install-the-skill): copy it from `@wringer/gunshi`, at the version the repo
|
|
50
51
|
installs.
|
|
51
52
|
- [The template](#the-template): the files to copy, with fixed parts and repo parts.
|
|
52
|
-
- [Create](#create): read the repo, then write the CLI, the actions, the checks, 3 to 5 features
|
|
53
|
-
the `verify` skill.
|
|
53
|
+
- [Create](#create): read the repo, then write the CLI, the actions, the checks, 3 to 5 features,
|
|
54
|
+
the ignore list and the `verify` skill.
|
|
54
55
|
- [Prove](#prove): doctor passes, a fresh subagent reaches `done` on every feature, and the CLI
|
|
55
56
|
refuses what it should.
|
|
56
57
|
- [Maintain](#maintain): the gate and `lint` in CI, and a template upgrade when `lint` asks.
|
|
@@ -96,7 +97,8 @@ Skip `verify-registry.test.ts` in `template/`: it tests the template inside wrin
|
|
|
96
97
|
|
|
97
98
|
These locations are defaults. When you change one, change each place that refers to it:
|
|
98
99
|
|
|
99
|
-
- the folder `scripts/verify/`: the `verify` script's path in `package.json
|
|
100
|
+
- the folder `scripts/verify/`: the `verify` script's path in `package.json`, and its glob in the
|
|
101
|
+
registry's `.ignore` list;
|
|
100
102
|
- the skill folder: `runVerify`'s `skill` option, a path from the repo root;
|
|
101
103
|
- the script name `verify`: the `package.json` script and the skill's `metadata.wringer-command`,
|
|
102
104
|
such as `bun verify`.
|
|
@@ -111,7 +113,8 @@ and the `#` title. Keep every other line. The repo owns `references/feature-map.
|
|
|
111
113
|
|
|
112
114
|
Read how the app starts, what it prints when it is ready, and which state it keeps. Then follow
|
|
113
115
|
[Create](./references/create.md): it ends with 3 to 5 features in the registry, each with a journey
|
|
114
|
-
in the `verify` skill, and `bun verify lint`
|
|
116
|
+
in the `verify` skill, an ignore list for the files with no runtime effect, and `bun verify lint`
|
|
117
|
+
passing.
|
|
115
118
|
|
|
116
119
|
## Prove
|
|
117
120
|
|
|
@@ -129,7 +132,9 @@ The work is done only when each of these holds. [Prove](./references/prove.md) g
|
|
|
129
132
|
|
|
130
133
|
Wire these into the repo, as [Maintain](./references/maintain.md) shows:
|
|
131
134
|
|
|
132
|
-
- **The gate on each PR.** A PR that touches a feature's `paths` needs a verdict
|
|
135
|
+
- **The gate on each PR.** A PR that touches a feature's `paths` needs a verdict recorded on the
|
|
136
|
+
PR's latest code. A PR that touches a file outside every feature's `paths` and the ignore list
|
|
137
|
+
fails until you add the file to one of them.
|
|
133
138
|
- **`lint` in CI.** It needs no running app.
|
|
134
139
|
- **A journey fixed with its feature.** A PR that changes a feature fixes the feature's journey.
|
|
135
140
|
|
|
@@ -11,6 +11,9 @@ The mistakes that cost the most:
|
|
|
11
11
|
action must declare its effect. A read-only target refuses each write with exit code 3.
|
|
12
12
|
- **A glob relative to a package.** Write each feature's `paths` globs relative to the repo root, as
|
|
13
13
|
`git ls-files` prints paths. In a monorepo, a glob relative to a package folder matches nothing.
|
|
14
|
+
- **Ignoring a file that changes behaviour.** Ignore only files the running app never reads, such as
|
|
15
|
+
docs and tests. The gate skips a file that an ignore glob matches, even when a feature's `paths`
|
|
16
|
+
match it too, so a change to it never needs a verdict.
|
|
14
17
|
- **A placeholder in a journey.** In the `verify` skill's fenced code blocks, `bun verify lint`
|
|
15
18
|
parses each line that starts with `bun verify`, and reads `<name>` as a shell redirect. Write each
|
|
16
19
|
such line as a command that runs, and put a command with a placeholder in inline code.
|
|
@@ -61,7 +64,13 @@ The mistakes that cost the most:
|
|
|
61
64
|
10. Write 3 to 5 features with `.feature`, each with `name`, `summary` and `paths`. Pick the
|
|
62
65
|
journeys users take most, from the app's routes and its README, and give each feature the globs
|
|
63
66
|
of the files that change its behaviour.
|
|
64
|
-
11.
|
|
67
|
+
11. The gate fails a PR that changes a file matched by neither a feature's `paths` nor an ignore
|
|
68
|
+
glob. Call `.ignore` with the globs of the files the running app never reads, such as `docs/**`,
|
|
69
|
+
`**/*.md`, `**/*.test.ts`, `.github/**`, `.claude/**` and `scripts/verify/**`. Add each other
|
|
70
|
+
file to the `paths` of each feature whose behaviour it changes: a file such as `package.json`
|
|
71
|
+
changes every feature. Expect: each file that `git ls-files` prints matches a feature's `paths`
|
|
72
|
+
or an ignore glob.
|
|
73
|
+
12. Copy [`template/verify/`](../template/verify/) to `.claude/skills/verify/`. Rewrite the
|
|
65
74
|
frontmatter's `name` and `description` and the `#` title for the app. Set
|
|
66
75
|
`metadata.wringer-command` to the command that runs the script, `bun verify` by default. Rewrite
|
|
67
76
|
each `<!-- repo: <part> -->` block:
|
|
@@ -75,7 +84,7 @@ The mistakes that cost the most:
|
|
|
75
84
|
form: what it does, how a user reaches it, its journey as a block of commands that run as
|
|
76
85
|
written, and its end state.
|
|
77
86
|
|
|
78
|
-
|
|
87
|
+
13. Run `bun verify lint`. Expect: `ok: true`, and `data.commands`, the count of journey lines it
|
|
79
88
|
parsed, above 0. A count of 0 means it found no journey.
|
|
80
|
-
|
|
89
|
+
14. Run `bun verify --help`, then `bun verify <group> --help` for each group it lists, such as
|
|
81
90
|
`action`. Expect: every action and repo command, each marked `[read]` or `[write]`.
|
|
@@ -17,10 +17,14 @@ The mistakes that cost the most:
|
|
|
17
17
|
## Wire the checks into CI
|
|
18
18
|
|
|
19
19
|
`bun verify lint` and `bun verify gate --base <ref> --body-file <file>` need no running app, so they
|
|
20
|
-
run in any job that has the repo's dependencies. The gate
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
code.
|
|
20
|
+
run in any job that has the repo's dependencies. The gate reads the last report block in the PR body
|
|
21
|
+
and works out the code's fingerprint itself. It fails with exit code 1 in two cases:
|
|
22
|
+
|
|
23
|
+
- A changed feature has no verdict, or a verdict for other code.
|
|
24
|
+
- A changed file matches neither a feature's `paths` nor a glob in the ignore list, which the
|
|
25
|
+
registry sets with `.ignore`. `bun verify gate` lists each such file in `data.unmapped`. When the
|
|
26
|
+
running app never reads the file, add it to the ignore list. Otherwise add it to a feature's
|
|
27
|
+
`paths`.
|
|
24
28
|
|
|
25
29
|
Add a workflow like this one. When the repo's other workflows pin each action to a commit SHA, pin
|
|
26
30
|
these the same way.
|
|
@@ -35,6 +35,8 @@ that adds them.
|
|
|
35
35
|
`error.code` `read-only`.
|
|
36
36
|
4. Run `bun verify detach`, then `bun verify use --target local`.
|
|
37
37
|
5. Run `bun verify report --human`. Expect: each feature whose `paths` match a file the branch
|
|
38
|
-
changes shows `verified`,
|
|
39
|
-
|
|
40
|
-
|
|
38
|
+
changes shows `verified`, every other feature shows `unchanged`, and the report lists no changed
|
|
39
|
+
path under "Changed paths that no feature maps". When it lists one, add the path to a feature's
|
|
40
|
+
`paths`, or to the registry's `.ignore` list when the running app never reads it. Then start
|
|
41
|
+
again at step 1. Paste the whole output into the PR description as it is, outside a code block.
|
|
42
|
+
The gate reads the report from the HTML comment at its end.
|
|
@@ -148,8 +148,9 @@ help marks each command `[read]` or `[write]`.
|
|
|
148
148
|
|
|
149
149
|
Before you run a feature's journey, read its entry in the
|
|
150
150
|
[feature map](./references/feature-map.md): what it does, how a user reaches it, its journey and its
|
|
151
|
-
end state. `bun verify features` lists each feature's `paths`.
|
|
152
|
-
match
|
|
151
|
+
end state. `bun verify features` lists each feature's `paths`. The gate needs a verdict for each
|
|
152
|
+
feature whose `paths` match a changed file. It fails on a changed file that matches neither a
|
|
153
|
+
feature's `paths` nor the registry's `.ignore` globs: add it to one of them.
|
|
153
154
|
|
|
154
155
|
## Update the feature map
|
|
155
156
|
|
|
@@ -78,5 +78,6 @@ export function createVerifyRegistry(): Wringer {
|
|
|
78
78
|
summary: 'Add an item from the pantry page',
|
|
79
79
|
paths: ['src/items/**', 'src/pages/pantry/**'],
|
|
80
80
|
})
|
|
81
|
+
.ignore('docs/**', '**/*.md', '**/*.test.ts', '.github/**', '.claude/**', 'scripts/verify/**')
|
|
81
82
|
.build();
|
|
82
83
|
}
|