@wringer/gunshi 0.2.0 → 0.3.1
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/README.md +25 -24
- package/dist/build-cli-wringer.d.ts +2 -0
- package/dist/build-guide-command.d.ts +2 -0
- package/dist/build-guide-ports.d.ts +4 -0
- package/dist/build-guide-wringer.d.ts +2 -0
- package/dist/build-lint-command.d.ts +1 -1
- package/dist/check-feature-file.d.ts +5 -0
- package/dist/collect-dead-globs.d.ts +3 -3
- package/dist/collect-unclaimed-files.d.ts +2 -0
- package/dist/parse-feature-table-span.d.ts +11 -0
- package/dist/parse-guide-topic.d.ts +6 -0
- package/dist/parse-skill-metadata.d.ts +1 -1
- package/dist/pick-guide-data.d.ts +20 -0
- package/dist/read-guide.d.ts +3 -0
- package/dist/read-template-hash.d.ts +1 -0
- package/dist/resolve-lint-failures.d.ts +6 -1
- package/dist/run-cli.d.ts +3 -1
- package/dist/run-verify.d.ts +3 -0
- package/dist/scrub-parsed-invocation.d.ts +3 -0
- package/{skills/wringer/references → guide}/create.md +30 -25
- package/{skills/wringer/references → guide}/fresh-subagent-brief.md +2 -0
- package/{skills/wringer/references → guide}/maintain.md +29 -22
- package/guide/overview.md +135 -0
- package/{skills/wringer/references → guide}/prove.md +16 -13
- package/guide/template/verify/SKILL.md +172 -0
- package/guide/template/verify/references/feature-add-item.md +20 -0
- package/{skills/wringer → guide}/template/verify-registry.ts +2 -1
- package/package.json +10 -9
- package/src/build-cli-wringer.ts +32 -0
- package/src/build-guide-command.ts +37 -0
- package/src/build-guide-ports.ts +73 -0
- package/src/build-guide-wringer.ts +19 -0
- package/src/build-lint-command.ts +32 -6
- package/src/check-feature-file.ts +105 -0
- package/src/collect-dead-globs.ts +18 -11
- package/src/collect-unclaimed-files.ts +17 -0
- package/src/parse-feature-table-span.ts +56 -0
- package/src/parse-guide-topic.ts +14 -0
- package/src/parse-skill-metadata.ts +8 -6
- package/src/pick-guide-data.ts +47 -0
- package/src/read-guide.ts +49 -0
- package/src/read-template-hash.ts +42 -0
- package/src/render-human-envelope.ts +7 -0
- package/src/resolve-lint-failures.ts +182 -11
- package/src/run-cli.ts +17 -2
- package/src/run-verify.ts +38 -15
- package/src/scrub-parsed-invocation.ts +32 -0
- package/src/wringer-gunshi.ts +7 -24
- package/dist/build-linted-wringer.d.ts +0 -2
- package/dist/find-skill-copy-refusal.d.ts +0 -8
- package/dist/parse-skill-install-args.d.ts +0 -3
- package/dist/template-version.d.ts +0 -1
- package/dist/write-skill-copy.d.ts +0 -12
- package/skills/wringer/SKILL.md +0 -143
- package/skills/wringer/template/verify/SKILL.md +0 -176
- package/skills/wringer/template/verify/references/feature-map.md +0 -17
- package/src/build-linted-wringer.ts +0 -16
- package/src/find-skill-copy-refusal.ts +0 -34
- package/src/parse-skill-install-args.ts +0 -25
- package/src/template-version.ts +0 -3
- package/src/write-skill-copy.ts +0 -75
- /package/{skills/wringer → guide}/template/verify.ts +0 -0
package/README.md
CHANGED
|
@@ -39,41 +39,42 @@ does on any duplicate name.
|
|
|
39
39
|
Markdown that tells the repo's agents how to use each feature. `lint` reads that folder. The path
|
|
40
40
|
defaults to `.claude/skills/verify`.
|
|
41
41
|
|
|
42
|
-
##
|
|
42
|
+
## Guide
|
|
43
43
|
|
|
44
|
-
The package ships
|
|
45
|
-
|
|
46
|
-
|
|
44
|
+
The package ships a guide in `guide/`. It walks an agent through adding a verify CLI, a feature map
|
|
45
|
+
and a verify skill to a repo, and through the checks that prove them. Its `template/` folder holds
|
|
46
|
+
the example files for the repo's own verify skill, which the agent writes.
|
|
47
47
|
|
|
48
|
-
The
|
|
49
|
-
first. After you install or upgrade the package, run the install command from the repo root:
|
|
48
|
+
The CLI prints the guide of the installed version, so no copy in the repo goes stale:
|
|
50
49
|
|
|
51
50
|
```bash
|
|
52
|
-
|
|
51
|
+
bun verify guide # the version and the topics
|
|
52
|
+
bun verify guide create # one topic
|
|
53
|
+
bunx wringer-gunshi guide # the same, for a repo that has no verify CLI yet
|
|
53
54
|
```
|
|
54
55
|
|
|
55
|
-
|
|
56
|
-
|
|
56
|
+
An unknown topic fails with `usage`, and its hint lists the topics. `guide template` prints the
|
|
57
|
+
absolute path of the installed template folder, to copy from. `--human` prints a topic's text alone.
|
|
57
58
|
|
|
58
59
|
## lint
|
|
59
60
|
|
|
60
|
-
`bun verify.ts lint` checks the
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- a
|
|
70
|
-
- a
|
|
71
|
-
|
|
72
|
-
|
|
61
|
+
`bun verify.ts lint` checks the features and the verify skill with no running app, so CI can run it
|
|
62
|
+
on a fresh checkout. It exits with code 1 and `check-failed` on any of these:
|
|
63
|
+
|
|
64
|
+
- a feature, `.shared()` or `.ignore()` glob that matches no file, or a file that no such glob
|
|
65
|
+
matches;
|
|
66
|
+
- a missing or orphaned `references/feature-<name>.md`, or a feature file without `## Journey` and
|
|
67
|
+
`## End state` or whose first `bash` line is not `<cli> use --feature <name>`;
|
|
68
|
+
- a `SKILL.md` feature table, between the `wringer:features` markers, that differs from
|
|
69
|
+
`features --markdown`;
|
|
70
|
+
- a registry file that no `.shared()` or feature `paths` glob matches;
|
|
71
|
+
- a line in a fenced code block of the skill's Markdown files that calls the CLI and fails to parse,
|
|
72
|
+
fails the command's schema, or names a feature or target the registry lacks;
|
|
73
|
+
- a missing `SKILL.md`, a frontmatter without `metadata.wringer-template` or
|
|
74
|
+
`metadata.wringer-command`, or another template hash. The `maintain` guide topic upgrades it.
|
|
73
75
|
|
|
74
76
|
`metadata.wringer-command` holds the words that call the CLI, such as `bun verify`. `lint` checks
|
|
75
|
-
only
|
|
76
|
-
assignments.
|
|
77
|
+
only code block lines that start with them, after an optional `$ ` prompt and assignments.
|
|
77
78
|
|
|
78
79
|
## Behaviour
|
|
79
80
|
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
import type { RegisteredCommand } from '@wringer/core';
|
|
2
|
-
export declare function buildLintCommand(skillFolder: string): RegisteredCommand;
|
|
2
|
+
export declare function buildLintCommand(skillFolder: string, registryFile: string | null): RegisteredCommand;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { Wringer } from '@wringer/core';
|
|
2
2
|
export interface DeadGlob {
|
|
3
|
-
readonly
|
|
3
|
+
readonly where: string;
|
|
4
4
|
readonly glob: string;
|
|
5
5
|
}
|
|
6
|
-
export declare function collectDeadGlobs(
|
|
6
|
+
export declare function collectDeadGlobs(wringer: Wringer, files: readonly string[]): readonly DeadGlob[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export type FeatureTableSpan = {
|
|
2
|
+
readonly ok: true;
|
|
3
|
+
readonly line: number;
|
|
4
|
+
readonly table: string;
|
|
5
|
+
} | {
|
|
6
|
+
readonly ok: false;
|
|
7
|
+
readonly line: number;
|
|
8
|
+
readonly reason: string;
|
|
9
|
+
};
|
|
10
|
+
export declare function parseFeatureTableSpan(text: string): FeatureTableSpan;
|
|
11
|
+
export declare function toComparableTable(table: string): string;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { WringerError } from '@wringer/core';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
import type { GuideTopic } from './parse-guide-topic.ts';
|
|
4
|
+
export declare const guideDataSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
5
|
+
version: z.ZodString;
|
|
6
|
+
topics: z.ZodArray<z.ZodObject<{
|
|
7
|
+
name: z.ZodString;
|
|
8
|
+
summary: z.ZodString;
|
|
9
|
+
}, z.core.$strict>>;
|
|
10
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
11
|
+
version: z.ZodString;
|
|
12
|
+
topic: z.ZodString;
|
|
13
|
+
text: z.ZodString;
|
|
14
|
+
}, z.core.$strict>]>;
|
|
15
|
+
export type GuideData = z.infer<typeof guideDataSchema>;
|
|
16
|
+
export interface Guide {
|
|
17
|
+
readonly version: string;
|
|
18
|
+
readonly topics: readonly GuideTopic[];
|
|
19
|
+
}
|
|
20
|
+
export declare function pickGuideData(guide: Guide, topic: string | undefined): GuideData | WringerError;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function readTemplateHash(folder?: string): Promise<string>;
|
|
@@ -3,9 +3,13 @@ import { z } from 'zod';
|
|
|
3
3
|
import type { MarkdownFile } from './collect-journey-commands.ts';
|
|
4
4
|
export declare const lintFailureSchema: z.ZodObject<{
|
|
5
5
|
check: z.ZodEnum<{
|
|
6
|
+
"feature-file": "feature-file";
|
|
7
|
+
"feature-table": "feature-table";
|
|
6
8
|
journey: "journey";
|
|
7
9
|
paths: "paths";
|
|
10
|
+
registry: "registry";
|
|
8
11
|
template: "template";
|
|
12
|
+
unclaimed: "unclaimed";
|
|
9
13
|
}>;
|
|
10
14
|
where: z.ZodString;
|
|
11
15
|
problem: z.ZodString;
|
|
@@ -15,8 +19,9 @@ export interface LintInput {
|
|
|
15
19
|
readonly wringer: Wringer;
|
|
16
20
|
readonly files: readonly string[];
|
|
17
21
|
readonly skillPath: string;
|
|
22
|
+
readonly registryFile: string | null;
|
|
18
23
|
readonly skillFiles: readonly MarkdownFile[];
|
|
19
|
-
readonly
|
|
24
|
+
readonly templateHash: string;
|
|
20
25
|
}
|
|
21
26
|
export interface LintResult {
|
|
22
27
|
readonly commands: number;
|
package/dist/run-cli.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
|
-
import type { RepoHost, StatePort, SupervisorPort, Wringer, WringerError } from '@wringer/core';
|
|
1
|
+
import type { PullRequestHost, RepoHost, StatePort, SupervisorPort, Wringer, WringerError } from '@wringer/core';
|
|
2
2
|
interface RepoPorts {
|
|
3
3
|
readonly state: StatePort;
|
|
4
4
|
readonly repoHost: RepoHost;
|
|
5
|
+
readonly pullRequests: PullRequestHost;
|
|
5
6
|
readonly supervisor: SupervisorPort;
|
|
6
7
|
}
|
|
7
8
|
export interface CLIPorts {
|
|
@@ -9,6 +10,7 @@ export interface CLIPorts {
|
|
|
9
10
|
readonly cwd: string;
|
|
10
11
|
readonly isTTY: boolean;
|
|
11
12
|
readonly isAgent: boolean;
|
|
13
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
12
14
|
readonly writeStdout: (text: string) => void;
|
|
13
15
|
readonly readRepoRoot: (cwd: string) => Promise<string | WringerError>;
|
|
14
16
|
readonly openRepo: (root: string) => RepoPorts;
|
package/dist/run-verify.d.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import type { Wringer } from '@wringer/core';
|
|
2
|
+
import type { CLIPorts } from './run-cli.ts';
|
|
2
3
|
export interface VerifyOptions {
|
|
3
4
|
readonly skill?: string | undefined;
|
|
5
|
+
readonly registry?: string | undefined;
|
|
4
6
|
}
|
|
5
7
|
export declare function runVerify(wringer: Wringer, options?: VerifyOptions): Promise<void>;
|
|
8
|
+
export declare function runWringer(wringer: Wringer, repoPorts?: Pick<CLIPorts, 'readRepoRoot' | 'openRepo'>): Promise<void>;
|
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
# Create
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
Write the verify CLI, its registry and the repo's verify skill
|
|
4
|
+
|
|
5
|
+
Add the verify CLI, its
|
|
6
|
+
[registry](https://github.com/zgeoff/wringer/blob/main/docs/reference/terms.md#registry) and the
|
|
7
|
+
repo's `verify` skill. `verify-registry.ts` in the template shows one target, driver, action, repo
|
|
8
|
+
command, doctor check and feature, on the builder that `createWringer` returns.
|
|
7
9
|
|
|
8
10
|
The mistakes that cost the most:
|
|
9
11
|
|
|
@@ -26,21 +28,22 @@ The mistakes that cost the most:
|
|
|
26
28
|
1. Install each driver the app needs, at an exact version, such as
|
|
27
29
|
`bun add --dev --exact @wringer/http`. Expect: each one in `devDependencies`.
|
|
28
30
|
|
|
29
|
-
| Driver
|
|
30
|
-
|
|
|
31
|
-
| `@wringer/browser`
|
|
32
|
-
| `@wringer/http`
|
|
33
|
-
| `@wringer/db`
|
|
34
|
-
| `@wringer/stream`
|
|
31
|
+
| Driver | Drives |
|
|
32
|
+
| ------------------- | -------------------------------------------- |
|
|
33
|
+
| `@wringer/browser` | a page, through its accessibility tree |
|
|
34
|
+
| `@wringer/http` | the app's HTTP API |
|
|
35
|
+
| `@wringer/db` | SQL on the app's SQLite or Postgres database |
|
|
36
|
+
| `@wringer/stream` | the app's logs, recorded for the whole run |
|
|
37
|
+
| `@wringer/terminal` | a text program, through its screen |
|
|
38
|
+
| `@wringer/mcp` | the tools of an MCP server |
|
|
35
39
|
|
|
36
40
|
Each driver adds its own commands and its own doctor check. Its README in `node_modules/` gives
|
|
37
41
|
its config for a target.
|
|
38
42
|
|
|
39
43
|
2. Add `.wringer/` to `.gitignore`. The CLI keeps each run's state and evidence there.
|
|
40
|
-
3. Copy
|
|
41
|
-
|
|
42
|
-
`
|
|
43
|
-
`bun verify --help` lists the template's commands.
|
|
44
|
+
3. Copy `verify.ts` and `verify-registry.ts` from the template (`bun verify guide template` names
|
|
45
|
+
its folder) into `scripts/verify/`. Add `"verify": "bun scripts/verify/verify.ts"` to the
|
|
46
|
+
`scripts` of `package.json`. Expect: `bun verify --help` lists the template's commands.
|
|
44
47
|
4. In `verify-registry.ts`, write the `local` target with `mode: 'launch'` and
|
|
45
48
|
`access: 'read-write'`. Its `launch` function returns:
|
|
46
49
|
- `command`: the command a developer runs to start the app;
|
|
@@ -66,23 +69,25 @@ The mistakes that cost the most:
|
|
|
66
69
|
of the files that change its behaviour.
|
|
67
70
|
11. The gate fails a PR that changes a file matched by neither a feature's `paths` nor an ignore
|
|
68
71
|
glob. Call `.ignore` with the globs of the files the running app never reads, such as `docs/**`,
|
|
69
|
-
`**/*.md`, `**/*.test.ts`, `.github
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
or
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
`
|
|
76
|
-
each `<!-- repo: <part> -->` block:
|
|
72
|
+
`**/*.md`, `**/*.test.ts`, `.github/**` and `.claude/**`. Add each other file to the `paths` of
|
|
73
|
+
each feature whose behaviour it changes: a file such as `package.json` changes every feature.
|
|
74
|
+
Call `.shared` with the globs of the files that change every feature, such as the registry's own
|
|
75
|
+
folder, because `lint` fails a registry file that no shared glob or `paths` glob matches.
|
|
76
|
+
Expect: each file that `git ls-files` prints matches a feature's `paths` or an ignore glob.
|
|
77
|
+
12. Copy `verify/` from the template to `.claude/skills/verify/`. Rewrite the frontmatter's `name`
|
|
78
|
+
and `description` and the `#` title for the app. Set `metadata.wringer-command` to the command
|
|
79
|
+
that runs the script, `bun verify` by default. Rewrite each `<!-- repo: <part> -->` block:
|
|
77
80
|
- `targets`: one row per target, with the command that starts a run, and what to do on a
|
|
78
81
|
refusal.
|
|
79
82
|
- `commands`: what `--help` can't say about the actions and repo commands, such as the order to
|
|
80
83
|
run them in.
|
|
81
84
|
- `registry`: the path of the registry file.
|
|
82
85
|
|
|
83
|
-
Then
|
|
84
|
-
form: what it does, how a user reaches it,
|
|
85
|
-
|
|
86
|
+
Then delete `references/feature-add-item.md` and write one `references/feature-<name>.md` per
|
|
87
|
+
feature, in the template's form: what it does, how a user reaches it, a `## Journey` section
|
|
88
|
+
whose first `bash` block starts with `bun verify use --feature <name>` and runs as written, and
|
|
89
|
+
a `## End state` section. Replace the feature table between the `wringer:features` markers with
|
|
90
|
+
the output of `bun verify features --markdown`.
|
|
86
91
|
|
|
87
92
|
13. Run `bun verify lint`. Expect: `ok: true`, and `data.commands`, the count of journey lines it
|
|
88
93
|
parsed, above 0. A count of 0 means it found no journey.
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Fresh subagent brief
|
|
2
2
|
|
|
3
|
+
The brief to send a fresh subagent that tries the verify skill
|
|
4
|
+
|
|
3
5
|
Send the brief below to a new general-purpose subagent. Never use a fork: a fork carries your
|
|
4
6
|
context, and the subagent must know only what the repo's `verify` skill tells it. Fill in the three
|
|
5
7
|
placeholders, and add nothing else. A fact you add about the app or the CLI hides a gap in the
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Maintain
|
|
2
2
|
|
|
3
|
+
Keep the gate, lint and the journeys true, and upgrade the verify skill
|
|
4
|
+
|
|
3
5
|
Wire `bun verify lint` and the gate into the repo's CI, fix a journey when its feature changes, and
|
|
4
6
|
upgrade the `verify` skill when `lint` reports an older template.
|
|
5
7
|
|
|
@@ -8,11 +10,9 @@ The mistakes that cost the most:
|
|
|
8
10
|
- **A shallow checkout.** The gate needs the merge base with the PR's base branch, so it fails on a
|
|
9
11
|
checkout without the full history.
|
|
10
12
|
- **No run on a body edit.** The gate reads the report from the PR body, so a run that skips the
|
|
11
|
-
`edited` event misses
|
|
13
|
+
`edited` event misses a report that `bun verify publish` writes later.
|
|
12
14
|
- **A nested copy.** `cp -R` into a folder that exists nests the copy inside it. Move the old
|
|
13
15
|
`verify` skill folder away first, as step 2 of the upgrade does.
|
|
14
|
-
`bunx @wringer/gunshi skill install` replaces the wringer skill's folder itself, so that folder
|
|
15
|
-
needs no move.
|
|
16
16
|
|
|
17
17
|
## Wire the checks into CI
|
|
18
18
|
|
|
@@ -20,7 +20,7 @@ The mistakes that cost the most:
|
|
|
20
20
|
run in any job that has the repo's dependencies. The gate reads the last report block in the PR body
|
|
21
21
|
and works out the code's fingerprint itself. It fails with exit code 1 in two cases:
|
|
22
22
|
|
|
23
|
-
- A changed feature has no verdict, or a verdict for other code.
|
|
23
|
+
- A changed feature has no verdict, or a verdict for other code in its own files or a shared path.
|
|
24
24
|
- A changed file matches neither a feature's `paths` nor a glob in the ignore list, which the
|
|
25
25
|
registry sets with `.ignore`. `bun verify gate` lists each such file in `data.unmapped`. When the
|
|
26
26
|
running app never reads the file, add it to the ignore list. Otherwise add it to a feature's
|
|
@@ -53,26 +53,33 @@ Keep it a workflow of its own, so a body edit reruns only this job.
|
|
|
53
53
|
|
|
54
54
|
A journey breaks when a change to its feature, such as a renamed button, makes a command of its
|
|
55
55
|
journey fail, or leaves the app different from the end state the journey expects. Fix the feature's
|
|
56
|
-
journey in the
|
|
57
|
-
`verify` skill's "Check a change" for that feature.
|
|
58
|
-
|
|
56
|
+
journey in the feature's `references/feature-<name>.md` in the `verify` skill, in the same PR. Then
|
|
57
|
+
follow the `verify` skill's "Check a change" for that feature. Run `bun verify publish` to replace
|
|
58
|
+
the report in the PR description.
|
|
59
59
|
|
|
60
60
|
## Upgrade the template
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Upgrade the repo's `verify` skill when `lint` fails with check `template`. The check fails when the
|
|
63
|
+
skill's `metadata.wringer-template` holds a version number, or a hash other than the hash of the
|
|
64
|
+
installed template.
|
|
63
65
|
|
|
64
|
-
1. Run `
|
|
65
|
-
|
|
66
|
-
2. Move the repo's `verify` skill folder
|
|
67
|
-
|
|
66
|
+
1. Run `bun verify guide template`. It names the folder of the template that the installed
|
|
67
|
+
`@wringer/gunshi` ships.
|
|
68
|
+
2. Move the repo's `verify` skill folder to a folder outside `.claude/skills/`, so it doesn't load
|
|
69
|
+
as a second skill. The skill folder is the path that the `skill` option of `runVerify` in
|
|
70
|
+
`verify.ts` names, such as `.claude/skills/verify/`. List the new folder in `.git/info/exclude`,
|
|
68
71
|
so git ignores it without a change to `.gitignore`.
|
|
69
|
-
3. Copy
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
`
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
72
|
+
3. Copy the template's `verify/` folder to the skill folder path, which step 2 emptied.
|
|
73
|
+
4. Delete the new skill's `references/feature-add-item.md`, the template's example feature, which
|
|
74
|
+
fails `lint` unless the repo has a feature of that name. Copy the old skill's
|
|
75
|
+
`references/feature-*.md` files into the new skill's `references/`.
|
|
76
|
+
5. In the new `SKILL.md`, replace the feature table between the `wringer:features` markers with the
|
|
77
|
+
output of `bun verify features --markdown`.
|
|
78
|
+
6. Copy the frontmatter's `name`, `description` and `metadata.wringer-command` from the old
|
|
79
|
+
`SKILL.md` into the new one. Copy the `#` title and each `<!-- repo -->` block too. When the new
|
|
80
|
+
template renames or adds a block, fill it from the old skill's matching content.
|
|
81
|
+
7. In the lockfile's git history, find the `@wringer/gunshi` version from before the bump. Read the
|
|
82
|
+
release notes of each later version on <https://github.com/zgeoff/wringer/releases>. Apply what
|
|
83
|
+
they ask of the `<!-- repo -->` blocks, `verify.ts` and the registry.
|
|
84
|
+
8. Run `bun verify lint`. Expect: `ok: true`. Then delete the old skill and its line in
|
|
85
|
+
`.git/info/exclude`.
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Build a verify CLI with wringer
|
|
2
|
+
|
|
3
|
+
What a verify CLI is, and the steps to add one to a repo and keep it true
|
|
4
|
+
|
|
5
|
+
Give the repo's agents one way to use its real app and keep the evidence of what they checked. Build
|
|
6
|
+
these in the repo:
|
|
7
|
+
|
|
8
|
+
- a verify CLI on the `@wringer/*` packages, which an agent runs as `bun verify <command>`;
|
|
9
|
+
- its [registry](https://github.com/zgeoff/wringer/blob/main/docs/reference/terms.md#registry), with
|
|
10
|
+
each feature's `paths` globs and the ignore list set with `.ignore`;
|
|
11
|
+
- a `verify` skill, with a feature file for each feature, `references/feature-<name>.md`, that gives
|
|
12
|
+
its journey and end state.
|
|
13
|
+
|
|
14
|
+
The [terms page](https://github.com/zgeoff/wringer/blob/main/docs/reference/terms.md) defines each
|
|
15
|
+
word this guide uses: registry, target, driver, action, command, feature, journey, run, doctor,
|
|
16
|
+
verdict, fingerprint, evidence, report, gate, shared glob and ignore list.
|
|
17
|
+
|
|
18
|
+
Then prove that the CLI, the registry and the skill work, and wire the checks that keep them true.
|
|
19
|
+
Hand back the PR that adds them, with the proof in its description. The mistakes that cost the most:
|
|
20
|
+
|
|
21
|
+
- **Calling the work done before a fresh agent uses the skill.** You know the app; the repo's next
|
|
22
|
+
agent knows only the `verify` skill. Run a subagent with none of your context to show that the
|
|
23
|
+
skill works.
|
|
24
|
+
- **Copying commands into the `verify` skill.** The CLI lists its own commands in `--help`, and a
|
|
25
|
+
copy goes stale. Point at `--help`, and write only what the help can't say.
|
|
26
|
+
- **A `paths` glob that matches no file.** The gate then fails on each file the glob should cover,
|
|
27
|
+
and lists it as unmapped. A file that another feature's glob covers passes. Run `bun verify lint`
|
|
28
|
+
to find such a glob.
|
|
29
|
+
- **Writing a repo's own choices outside the `<!-- repo -->` blocks of the `verify` skill.** An
|
|
30
|
+
upgrade of the template replaces every line outside them. Put each choice, such as where an agent
|
|
31
|
+
reports a refused write, in a block or in the repo's code.
|
|
32
|
+
|
|
33
|
+
## Key rules
|
|
34
|
+
|
|
35
|
+
- [Topics](#topics): `guide <topic>` prints the commands for each step.
|
|
36
|
+
- [Install](#install): add the packages, then read this guide from the CLI at the version the repo
|
|
37
|
+
installs.
|
|
38
|
+
- [The template](#the-template): the files to copy, with fixed parts and repo parts.
|
|
39
|
+
- [Create](#create): read the repo, then write the CLI, the actions, the checks, 3 to 5 features,
|
|
40
|
+
the ignore list and the `verify` skill.
|
|
41
|
+
- [Prove](#prove): doctor passes, a fresh subagent reaches `done` on every feature, the CLI refuses
|
|
42
|
+
a command before the doctor passes and a write on a read-only target, and `bun verify publish`
|
|
43
|
+
writes the report into the PR.
|
|
44
|
+
- [Maintain](#maintain): the gate and `lint` in CI, and a template upgrade when `lint` asks.
|
|
45
|
+
|
|
46
|
+
## Topics
|
|
47
|
+
|
|
48
|
+
Run `bunx wringer-gunshi guide <topic>` in a repo with no verify CLI yet, or
|
|
49
|
+
`bun verify guide <topic>` in one that has it. Each prints the guide of the installed
|
|
50
|
+
`@wringer/gunshi`, so it matches the packages the repo runs.
|
|
51
|
+
|
|
52
|
+
- `create`: writing the CLI, the registry and the `verify` skill in a repo.
|
|
53
|
+
- `prove`: the proof steps and what each shows in the PR.
|
|
54
|
+
- `fresh-subagent-brief`: the brief to give the subagent in the prove flow.
|
|
55
|
+
- `maintain`: wiring the gate and `lint` into CI, and upgrading the template.
|
|
56
|
+
- `template`: where the template files are, to copy from.
|
|
57
|
+
|
|
58
|
+
## Install
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
bun add --dev --exact @wringer/core @wringer/gunshi zod
|
|
62
|
+
bunx wringer-gunshi guide
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The second command lists the topics. Read the guide again after each upgrade of `@wringer/gunshi`.
|
|
66
|
+
|
|
67
|
+
The CLI runs on Bun. When the repo installs packages with another package manager, use it for
|
|
68
|
+
`bun add` and `bunx`, such as `pnpm add` and `pnpm dlx`. Also use it in the `verify` skill's
|
|
69
|
+
`metadata.wringer-command`, such as `pnpm verify`. The `verify` script in `package.json` still runs
|
|
70
|
+
the CLI with `bun`.
|
|
71
|
+
|
|
72
|
+
## The template
|
|
73
|
+
|
|
74
|
+
`bun verify guide template`, or `bunx wringer-gunshi guide template` before the repo has a verify
|
|
75
|
+
CLI, prints the absolute path of the installed template folder. It holds a working example for an
|
|
76
|
+
invented app, Larder:
|
|
77
|
+
|
|
78
|
+
| File | Copy to | Holds |
|
|
79
|
+
| -------------------- | ----------------------------------- | ----------------------------------------------------------------- |
|
|
80
|
+
| `verify.ts` | `scripts/verify/verify.ts` | the entry point that calls `runVerify` |
|
|
81
|
+
| `verify-registry.ts` | `scripts/verify/verify-registry.ts` | targets, a driver, an action, a command, a check, a feature |
|
|
82
|
+
| `verify/` | `.claude/skills/verify/` | the repo's `verify` skill, and its feature files in `references/` |
|
|
83
|
+
|
|
84
|
+
Skip `verify-registry.test.ts` in the template: it tests the template inside wringer.
|
|
85
|
+
|
|
86
|
+
These locations are defaults. When you change one, change each place that refers to it:
|
|
87
|
+
|
|
88
|
+
- the folder `scripts/verify/`:
|
|
89
|
+
- the `verify` script's path in `package.json`;
|
|
90
|
+
- its glob in the registry's `.shared` list;
|
|
91
|
+
- the `registry` option of `runVerify`, when the registry lives apart from `verify.ts`;
|
|
92
|
+
- the skill folder: `runVerify`'s `skill` option, a path from the repo root;
|
|
93
|
+
- the script name `verify`: the `package.json` script and the skill's `metadata.wringer-command`,
|
|
94
|
+
such as `bun verify`.
|
|
95
|
+
|
|
96
|
+
In the `verify` skill's `SKILL.md`, each `<!-- repo: <part> -->` block ends at `<!-- /repo -->` and
|
|
97
|
+
holds what only this repo knows. Rewrite those blocks, the frontmatter's `name` and `description`,
|
|
98
|
+
and the `#` title. Keep every other line. The repo owns each `references/feature-*.md` whole. Keep
|
|
99
|
+
`metadata.wringer-template` as the template has it. `lint` compares that value with the hash of the
|
|
100
|
+
template that the installed `@wringer/gunshi` ships. The `maintain` topic's upgrade copies in the
|
|
101
|
+
new value.
|
|
102
|
+
|
|
103
|
+
## Create
|
|
104
|
+
|
|
105
|
+
Read how the app starts, what it prints when it is ready, and which state it keeps. Then follow the
|
|
106
|
+
`create` topic: it ends with 3 to 5 features in the registry, each with a journey in the `verify`
|
|
107
|
+
skill, an ignore list for the files with no runtime effect, and `bun verify lint` passing.
|
|
108
|
+
|
|
109
|
+
## Prove
|
|
110
|
+
|
|
111
|
+
The work is done only when each of these holds. The `prove` topic gives the commands.
|
|
112
|
+
|
|
113
|
+
1. `bun verify doctor` passes on `local`.
|
|
114
|
+
2. A fresh subagent that loads only the new `verify` skill reaches `done` on every feature. New
|
|
115
|
+
feature files need one pass by an agent who did not write it, and this run is that pass.
|
|
116
|
+
3. After an edit to a file that a feature's `paths` match, a command that touches the app fails with
|
|
117
|
+
`doctor-required`. On a read-only target, if the repo has one, try one write: the CLI refuses it
|
|
118
|
+
with `read-only`.
|
|
119
|
+
4. `bun verify publish` has written the report into the description of the PR that adds the CLI. The
|
|
120
|
+
gate reads the report from the HTML comment at the report's end.
|
|
121
|
+
|
|
122
|
+
## Maintain
|
|
123
|
+
|
|
124
|
+
Keep these in place, as the `maintain` topic shows:
|
|
125
|
+
|
|
126
|
+
- **The gate on each PR.** A PR that touches a feature's `paths` needs a verdict that the agent
|
|
127
|
+
recorded with `bun verify done` on the PR's latest code. A PR that touches a file outside every
|
|
128
|
+
feature's `paths` and the ignore list fails until you add the file to one of them.
|
|
129
|
+
- **`lint` in CI.** It needs no running app. When it reports another template hash, upgrade the
|
|
130
|
+
template as the `maintain` topic says.
|
|
131
|
+
- **A journey fixed with its feature.** A PR that changes a feature updates the feature's journey.
|
|
132
|
+
|
|
133
|
+
Don't add a scheduled job. The gate checks a feature each time a PR changes it.
|
|
134
|
+
|
|
135
|
+
**Reply:** the PR link, and for each prove step, the command and the output lines that show it held.
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# Prove
|
|
2
2
|
|
|
3
|
-
Prove
|
|
4
|
-
|
|
3
|
+
Prove the verify CLI, its registry and its skill work before the PR
|
|
4
|
+
|
|
5
|
+
Prove that the verify CLI, its registry and the repo's `verify` skill work before you ask for review
|
|
6
|
+
of the PR that adds them.
|
|
5
7
|
|
|
6
8
|
- Make every change to the code, the registry and the `verify` skill before step 2. A verdict holds
|
|
7
9
|
for the code as it was at `done`: an edit makes it stale, and undoing the edit makes it hold
|
|
@@ -15,14 +17,14 @@ that adds them.
|
|
|
15
17
|
|
|
16
18
|
1. Run `bun verify up`, then `bun verify doctor`. Expect: the doctor's last JSON line has `ok: true`
|
|
17
19
|
and `data.passed: true`. Then run `bun verify down`.
|
|
18
|
-
2. Send the
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
20
|
+
2. Send the brief of `guide fresh-subagent-brief` to a new subagent, and follow that reference until
|
|
21
|
+
one subagent reaches `done` on every feature and names no gap. Expect: its reply, with exit code
|
|
22
|
+
0 from each `done`. Put the subagent's result for each `done` in the PR: the feature, the exit
|
|
23
|
+
code, `ok` and `data.fingerprint`.
|
|
22
24
|
3. Check that the CLI refuses to run against a changed tree:
|
|
23
25
|
1. Run `bun verify up`, then `bun verify doctor`. Expect: `data.passed: true`.
|
|
24
26
|
2. Add a blank line to a file that a feature's `paths` globs match.
|
|
25
|
-
3. From that feature's journey in the `verify` skill's feature
|
|
27
|
+
3. From that feature's journey in the `verify` skill's feature file, run one command that touches
|
|
26
28
|
the app, such as an `action` or a `browser` command. Expect: exit code 3 and `error.code`
|
|
27
29
|
`doctor-required`.
|
|
28
30
|
4. Undo the edit, and run `bun verify down`.
|
|
@@ -34,9 +36,10 @@ that adds them.
|
|
|
34
36
|
3. Run one command that `--help` marks `[write]`, such as a write action. Expect: exit code 3 and
|
|
35
37
|
`error.code` `read-only`.
|
|
36
38
|
4. Run `bun verify detach`, then `bun verify use --target local`.
|
|
37
|
-
5. Run `bun verify report --human
|
|
38
|
-
changes shows `verified`, every other feature shows `unchanged`, and the
|
|
39
|
-
path under "Changed paths that no feature maps". When it lists one, add
|
|
40
|
-
`paths`, or to the registry's `.ignore` list when the running app never
|
|
41
|
-
again at step 1.
|
|
42
|
-
|
|
39
|
+
5. Run `bun verify report --human` to read the report locally. Expect: each feature whose `paths`
|
|
40
|
+
match a file the branch changes shows `verified`, every other feature shows `unchanged`, and the
|
|
41
|
+
report lists no changed path under "Changed paths that no feature maps". When it lists one, add
|
|
42
|
+
the path to a feature's `paths`, or to the registry's `.ignore` list when the running app never
|
|
43
|
+
reads it. Then start again at step 1. Otherwise push the branch and open its PR. Then run
|
|
44
|
+
`bun verify publish`. Expect: `ok: true`. It writes the report into the PR description, and the
|
|
45
|
+
gate reads the report from the HTML comment at the report's end.
|