@wringer/gunshi 0.0.0 → 0.1.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 +45 -2
- package/dist/build-lint-command.d.ts +2 -0
- package/dist/build-linted-wringer.d.ts +2 -0
- package/dist/collect-dead-globs.d.ts +6 -0
- package/dist/collect-journey-commands.d.ts +11 -0
- package/dist/collect-lint-files.d.ts +11 -0
- package/dist/find-skill-copy-refusal.d.ts +8 -0
- package/dist/index.d.ts +1 -0
- package/dist/parse-shell-words.d.ts +1 -0
- package/dist/parse-skill-install-args.d.ts +3 -0
- package/dist/parse-skill-metadata.d.ts +9 -0
- package/dist/resolve-invocation.d.ts +3 -0
- package/dist/resolve-journey-problem.d.ts +2 -0
- package/dist/resolve-lint-failures.d.ts +26 -0
- package/dist/run-cli.d.ts +1 -2
- package/dist/run-verify.d.ts +4 -1
- package/dist/template-version.d.ts +1 -0
- package/dist/wringer-gunshi.d.ts +2 -0
- package/dist/write-skill-copy.d.ts +12 -0
- package/package.json +13 -6
- package/skills/wringer/SKILL.md +138 -0
- package/skills/wringer/references/create.md +81 -0
- package/skills/wringer/references/fresh-subagent-brief.md +34 -0
- package/skills/wringer/references/maintain.md +74 -0
- package/skills/wringer/references/prove.md +40 -0
- package/skills/wringer/template/verify/SKILL.md +175 -0
- package/skills/wringer/template/verify/references/feature-map.md +17 -0
- package/skills/wringer/template/verify-registry.ts +82 -0
- package/skills/wringer/template/verify.ts +6 -0
- package/src/build-lint-command.ts +91 -0
- package/src/build-linted-wringer.ts +16 -0
- package/src/collect-dead-globs.ts +21 -0
- package/src/collect-journey-commands.ts +140 -0
- package/src/collect-lint-files.ts +36 -0
- package/src/find-skill-copy-refusal.ts +34 -0
- package/src/index.ts +1 -0
- package/src/parse-shell-words.ts +67 -0
- package/src/parse-skill-install-args.ts +25 -0
- package/src/parse-skill-metadata.ts +56 -0
- package/src/resolve-invocation.ts +94 -0
- package/src/resolve-journey-problem.ts +64 -0
- package/src/resolve-lint-failures.ts +111 -0
- package/src/run-cli.ts +6 -97
- package/src/run-verify.ts +27 -16
- package/src/template-version.ts +3 -0
- package/src/wringer-gunshi.ts +27 -0
- package/src/write-skill-copy.ts +75 -0
package/README.md
CHANGED
|
@@ -26,11 +26,54 @@ Call `runVerify` from the repo's verify script with the registry that `@wringer/
|
|
|
26
26
|
import { runVerify } from '@wringer/gunshi';
|
|
27
27
|
import { registry } from './registry.ts';
|
|
28
28
|
|
|
29
|
-
await runVerify(registry);
|
|
29
|
+
await runVerify(registry, { skill: '.claude/skills/verify' });
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
Run it as `bun verify.ts <command>`, for example `bun verify.ts up` or
|
|
33
|
-
`bun verify.ts action seed --count 3`.
|
|
33
|
+
`bun verify.ts action seed --count 3`. The CLI lists the built-in commands, such as `up`, `doctor`
|
|
34
|
+
and `lint`, beside the commands that the registry declares and that its drivers add. A registry
|
|
35
|
+
can't declare a command named `lint`: `runVerify` throws `Two commands share the name`, as `build()`
|
|
36
|
+
does on any duplicate name.
|
|
37
|
+
|
|
38
|
+
`skill` is the path, from the repo root, of the folder that holds the repo's verify skill: the
|
|
39
|
+
Markdown that tells the repo's agents how to use each feature. `lint` reads that folder. The path
|
|
40
|
+
defaults to `.claude/skills/verify`.
|
|
41
|
+
|
|
42
|
+
## Agent skill
|
|
43
|
+
|
|
44
|
+
The package ships an agent skill in `skills/wringer/`. It walks an agent through adding a verify
|
|
45
|
+
CLI, a feature map and a verify skill to a repo, and through the checks that prove them. Its
|
|
46
|
+
`template/` folder holds the example files for the repo's own verify skill, which the agent writes.
|
|
47
|
+
|
|
48
|
+
The install command deletes the folder it installs to, so move any edits out of the repo's copy
|
|
49
|
+
first. After you install or upgrade the package, run the install command from the repo root:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
bunx @wringer/gunshi skill install
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
It copies the skill from the installed package to `.claude/skills/wringer`, or to `--dir <path>`. It
|
|
56
|
+
refuses a folder that is not a copy of this agent skill, and exits with code 2.
|
|
57
|
+
|
|
58
|
+
## lint
|
|
59
|
+
|
|
60
|
+
`bun verify.ts lint` checks the feature map and the verify skill without starting the app, so CI can
|
|
61
|
+
run it on a fresh checkout. It exits with code 1, with `check-failed` in its envelope's
|
|
62
|
+
`error.code`, when it finds any of these:
|
|
63
|
+
|
|
64
|
+
- a feature's `paths` glob that matches no tracked file, and no untracked file outside git's ignore
|
|
65
|
+
rules;
|
|
66
|
+
- a line in a fenced code block of the verify skill's Markdown files that calls the CLI and fails to
|
|
67
|
+
parse, whose arguments fail the command's schema, or that names a feature or a target the registry
|
|
68
|
+
lacks;
|
|
69
|
+
- a skill folder with no `SKILL.md`;
|
|
70
|
+
- a verify skill whose frontmatter lacks `metadata.wringer-template` or `metadata.wringer-command`,
|
|
71
|
+
or whose `metadata.wringer-template` differs from the template version that this package ships.
|
|
72
|
+
The agent skill's upgrade steps bring the verify skill to the shipped version.
|
|
73
|
+
|
|
74
|
+
`metadata.wringer-command` holds the words that call the CLI, such as `bun verify`. `lint` checks
|
|
75
|
+
only the code block lines that start with those words, after an optional `$ ` prompt and environment
|
|
76
|
+
assignments.
|
|
34
77
|
|
|
35
78
|
## Behaviour
|
|
36
79
|
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { FeatureDefinition } from '@wringer/core';
|
|
2
|
+
export interface DeadGlob {
|
|
3
|
+
readonly feature: string;
|
|
4
|
+
readonly glob: string;
|
|
5
|
+
}
|
|
6
|
+
export declare function collectDeadGlobs(features: readonly FeatureDefinition[], files: readonly string[]): readonly DeadGlob[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface MarkdownFile {
|
|
2
|
+
readonly path: string;
|
|
3
|
+
readonly text: string;
|
|
4
|
+
}
|
|
5
|
+
export interface JourneyCommand {
|
|
6
|
+
readonly path: string;
|
|
7
|
+
readonly line: number;
|
|
8
|
+
readonly text: string;
|
|
9
|
+
readonly argv: readonly string[] | null;
|
|
10
|
+
}
|
|
11
|
+
export declare function collectJourneyCommands(files: readonly MarkdownFile[], cliWords: readonly string[]): readonly JourneyCommand[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface LintFileListing {
|
|
2
|
+
readonly listed: string;
|
|
3
|
+
readonly deleted: string;
|
|
4
|
+
readonly skillFolder: string;
|
|
5
|
+
}
|
|
6
|
+
export interface LintFiles {
|
|
7
|
+
readonly files: readonly string[];
|
|
8
|
+
readonly skillFolder: string;
|
|
9
|
+
readonly skillMarkdown: readonly string[];
|
|
10
|
+
}
|
|
11
|
+
export declare function collectLintFiles(listing: LintFileListing): LintFiles;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export type DestinationState = 'absent' | 'wringer-skill' | 'other';
|
|
2
|
+
export interface SkillCopyPlan {
|
|
3
|
+
readonly source: string;
|
|
4
|
+
readonly destination: string;
|
|
5
|
+
readonly cwd: string;
|
|
6
|
+
readonly state: DestinationState;
|
|
7
|
+
}
|
|
8
|
+
export declare function findSkillCopyRefusal(plan: SkillCopyPlan): string | null;
|
package/dist/index.d.ts
CHANGED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function parseShellWords(line: string): readonly string[] | null;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { Wringer } from '@wringer/core';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
import type { MarkdownFile } from './collect-journey-commands.ts';
|
|
4
|
+
export declare const lintFailureSchema: z.ZodObject<{
|
|
5
|
+
check: z.ZodEnum<{
|
|
6
|
+
journey: "journey";
|
|
7
|
+
paths: "paths";
|
|
8
|
+
template: "template";
|
|
9
|
+
}>;
|
|
10
|
+
where: z.ZodString;
|
|
11
|
+
problem: z.ZodString;
|
|
12
|
+
}, z.core.$strict>;
|
|
13
|
+
type LintFailure = z.infer<typeof lintFailureSchema>;
|
|
14
|
+
export interface LintInput {
|
|
15
|
+
readonly wringer: Wringer;
|
|
16
|
+
readonly files: readonly string[];
|
|
17
|
+
readonly skillPath: string;
|
|
18
|
+
readonly skillFiles: readonly MarkdownFile[];
|
|
19
|
+
readonly templateVersion: number;
|
|
20
|
+
}
|
|
21
|
+
export interface LintResult {
|
|
22
|
+
readonly commands: number;
|
|
23
|
+
readonly failures: readonly LintFailure[];
|
|
24
|
+
}
|
|
25
|
+
export declare function resolveLintFailures(input: LintInput): Promise<LintResult>;
|
|
26
|
+
export {};
|
package/dist/run-cli.d.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import { WringerError } from '@wringer/core';
|
|
2
|
-
import type { RepoHost, StatePort, SupervisorPort, Wringer } from '@wringer/core';
|
|
1
|
+
import type { RepoHost, StatePort, SupervisorPort, Wringer, WringerError } from '@wringer/core';
|
|
3
2
|
interface RepoPorts {
|
|
4
3
|
readonly state: StatePort;
|
|
5
4
|
readonly repoHost: RepoHost;
|
package/dist/run-verify.d.ts
CHANGED
|
@@ -1,2 +1,5 @@
|
|
|
1
1
|
import type { Wringer } from '@wringer/core';
|
|
2
|
-
export
|
|
2
|
+
export interface VerifyOptions {
|
|
3
|
+
readonly skill?: string | undefined;
|
|
4
|
+
}
|
|
5
|
+
export declare function runVerify(wringer: Wringer, options?: VerifyOptions): Promise<void>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const templateVersion = 1;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export interface SkillCopyPaths {
|
|
2
|
+
readonly source: string;
|
|
3
|
+
readonly destination: string;
|
|
4
|
+
readonly cwd: string;
|
|
5
|
+
}
|
|
6
|
+
export type SkillCopyResult = {
|
|
7
|
+
readonly ok: true;
|
|
8
|
+
} | {
|
|
9
|
+
readonly ok: false;
|
|
10
|
+
readonly reason: string;
|
|
11
|
+
};
|
|
12
|
+
export declare function writeSkillCopy(paths: SkillCopyPaths): Promise<SkillCopyResult>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wringer/gunshi",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.1",
|
|
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",
|
|
@@ -10,11 +10,16 @@
|
|
|
10
10
|
"url": "git+https://github.com/zgeoff/wringer.git",
|
|
11
11
|
"directory": "packages/gunshi"
|
|
12
12
|
},
|
|
13
|
+
"bin": {
|
|
14
|
+
"wringer-gunshi": "./src/wringer-gunshi.ts"
|
|
15
|
+
},
|
|
13
16
|
"files": [
|
|
14
17
|
"src",
|
|
15
18
|
"!src/**/*.test.ts",
|
|
16
19
|
"dist",
|
|
17
|
-
"!src/test-utils"
|
|
20
|
+
"!src/test-utils",
|
|
21
|
+
"skills",
|
|
22
|
+
"!skills/**/*.test.ts"
|
|
18
23
|
],
|
|
19
24
|
"type": "module",
|
|
20
25
|
"exports": {
|
|
@@ -32,15 +37,17 @@
|
|
|
32
37
|
},
|
|
33
38
|
"dependencies": {
|
|
34
39
|
"gunshi": "0.37.3",
|
|
40
|
+
"tiny-invariant": "1.3.3",
|
|
41
|
+
"ts-pattern": "5.9.2",
|
|
35
42
|
"zod": "4.6.7"
|
|
36
43
|
},
|
|
37
44
|
"devDependencies": {
|
|
38
|
-
"@wringer/core": "0.1.
|
|
39
|
-
"@
|
|
40
|
-
"
|
|
45
|
+
"@wringer/core": "0.1.2",
|
|
46
|
+
"@wringer/http": "0.1.1",
|
|
47
|
+
"@zgeoff/testing": "0.3.0"
|
|
41
48
|
},
|
|
42
49
|
"peerDependencies": {
|
|
43
|
-
"@wringer/core": "0.1.
|
|
50
|
+
"@wringer/core": "0.1.2"
|
|
44
51
|
},
|
|
45
52
|
"engines": {
|
|
46
53
|
"bun": ">=1.3"
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: wringer
|
|
3
|
+
description:
|
|
4
|
+
"Builds a repo's verify CLI, feature map and verify skill on wringer, proves them, and keeps them
|
|
5
|
+
true. Load it to add wringer to a repo, to prove a verify CLI before its PR, when `verify lint`
|
|
6
|
+
fails, or when a new @wringer/gunshi ships a new template version."
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Build a verify CLI with wringer
|
|
10
|
+
|
|
11
|
+
Give the repo's agents one way to use its real app and keep the evidence of what they checked. Build
|
|
12
|
+
these in the repo:
|
|
13
|
+
|
|
14
|
+
- a verify CLI on the `@wringer/*` packages, which an agent runs as `bun verify <command>`;
|
|
15
|
+
- its registry: the code that declares the targets, the drivers, the actions, the doctor checks and
|
|
16
|
+
the features, where each feature lists the `paths` globs of its files;
|
|
17
|
+
- a `verify` skill, with a feature map in its `references/feature-map.md` that gives each feature's
|
|
18
|
+
journey.
|
|
19
|
+
|
|
20
|
+
These terms hold across this skill and its references:
|
|
21
|
+
|
|
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 that changes a feature's files without a verdict |
|
|
32
|
+
| report | the output of `bun verify report --human`, which the PR body holds for the gate |
|
|
33
|
+
|
|
34
|
+
Then prove them, and wire the checks that keep them true. Hand back the PR that adds them, with the
|
|
35
|
+
proof in its description. The mistakes that cost the most:
|
|
36
|
+
|
|
37
|
+
- **Calling it done before a fresh agent uses it.** You know the app; the repo's next agent knows
|
|
38
|
+
only the `verify` skill. Run a subagent with none of your context to show that the skill works.
|
|
39
|
+
- **Copying commands into the `verify` skill.** The CLI lists its own commands in `--help`, and a
|
|
40
|
+
copy goes stale. Point at `--help`, and write only what the help can't say.
|
|
41
|
+
- **A `paths` glob that matches no file.** A change to that feature's files then never needs its
|
|
42
|
+
verdict. Run `bun verify lint` to find one.
|
|
43
|
+
- **Writing a repo's own choices outside the `<!-- repo -->` blocks of the `verify` skill.** An
|
|
44
|
+
upgrade of the template replaces every line outside them. Put each choice, such as where an agent
|
|
45
|
+
reports a refused write, in a block or in the repo's code.
|
|
46
|
+
|
|
47
|
+
## Key rules
|
|
48
|
+
|
|
49
|
+
- [Install the skill](#install-the-skill): copy it from `@wringer/gunshi`, at the version the repo
|
|
50
|
+
installs.
|
|
51
|
+
- [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 and
|
|
53
|
+
the `verify` skill.
|
|
54
|
+
- [Prove](#prove): doctor passes, a fresh subagent reaches `done` on every feature, and the CLI
|
|
55
|
+
refuses what it should.
|
|
56
|
+
- [Maintain](#maintain): the gate and `lint` in CI, and a template upgrade when `lint` asks.
|
|
57
|
+
|
|
58
|
+
## References
|
|
59
|
+
|
|
60
|
+
- [Create](./references/create.md): writing the CLI, the registry and the `verify` skill in a repo.
|
|
61
|
+
- [Prove](./references/prove.md): the proof steps and what each shows in the PR.
|
|
62
|
+
- [Fresh subagent brief](./references/fresh-subagent-brief.md): the brief to give the subagent in
|
|
63
|
+
the prove flow.
|
|
64
|
+
- [Maintain](./references/maintain.md): wiring the gate and `lint` into CI, and upgrading the
|
|
65
|
+
template.
|
|
66
|
+
|
|
67
|
+
## Install the skill
|
|
68
|
+
|
|
69
|
+
This skill ships inside `@wringer/gunshi`, so its version matches the packages the repo installs.
|
|
70
|
+
These commands put it in `.claude/skills/wringer/`, where an agent can load it, and replace any
|
|
71
|
+
older copy there. Commit that folder with the rest of the work:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
bun add --dev --exact @wringer/core @wringer/gunshi zod
|
|
75
|
+
bunx @wringer/gunshi skill install
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Run the second command again after each upgrade of `@wringer/gunshi`.
|
|
79
|
+
|
|
80
|
+
The CLI runs on Bun. When the repo installs packages with another package manager, use it for
|
|
81
|
+
`bun add` and `bunx`, such as `pnpm add` and `pnpm dlx`. Also use it in the `verify` skill's
|
|
82
|
+
`metadata.wringer-command`, such as `pnpm verify`. The `verify` script in `package.json` still runs
|
|
83
|
+
the CLI with `bun`.
|
|
84
|
+
|
|
85
|
+
## The template
|
|
86
|
+
|
|
87
|
+
[`template/`](./template/) holds a working example for an invented app, Larder:
|
|
88
|
+
|
|
89
|
+
| File | Copy to | Holds |
|
|
90
|
+
| ----------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------- |
|
|
91
|
+
| [`verify.ts`](./template/verify.ts) | `scripts/verify/verify.ts` | the entry point that calls `runVerify` |
|
|
92
|
+
| [`verify-registry.ts`](./template/verify-registry.ts) | `scripts/verify/verify-registry.ts` | targets, a driver, an action, a command, a check, a feature |
|
|
93
|
+
| [`verify/`](./template/verify/) | `.claude/skills/verify/` | the repo's `verify` skill, and its feature map in `references/` |
|
|
94
|
+
|
|
95
|
+
Skip `verify-registry.test.ts` in `template/`: it tests the template inside wringer.
|
|
96
|
+
|
|
97
|
+
These locations are defaults. When you change one, change each place that refers to it:
|
|
98
|
+
|
|
99
|
+
- the folder `scripts/verify/`: the `verify` script's path in `package.json`;
|
|
100
|
+
- the skill folder: `runVerify`'s `skill` option, a path from the repo root;
|
|
101
|
+
- the script name `verify`: the `package.json` script and the skill's `metadata.wringer-command`,
|
|
102
|
+
such as `bun verify`.
|
|
103
|
+
|
|
104
|
+
In the `verify` skill's `SKILL.md`, each `<!-- repo: <part> -->` block ends at `<!-- /repo -->` and
|
|
105
|
+
holds what only this repo knows. Rewrite those blocks, the frontmatter's `name` and `description`,
|
|
106
|
+
and the `#` title. Keep every other line. The repo owns `references/feature-map.md` whole. Keep
|
|
107
|
+
`metadata.wringer-template` as the template has it: `lint` compares it with the version that
|
|
108
|
+
`@wringer/gunshi` ships.
|
|
109
|
+
|
|
110
|
+
## Create
|
|
111
|
+
|
|
112
|
+
Read how the app starts, what it prints when it is ready, and which state it keeps. Then follow
|
|
113
|
+
[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` passing.
|
|
115
|
+
|
|
116
|
+
## Prove
|
|
117
|
+
|
|
118
|
+
The work is done only when each of these holds. [Prove](./references/prove.md) gives the commands.
|
|
119
|
+
|
|
120
|
+
1. `bun verify doctor` passes on `local`.
|
|
121
|
+
2. A fresh subagent that loads only the new `verify` skill reaches `done` on every feature. A new
|
|
122
|
+
feature map needs one pass by an agent who did not write it, and this run is that pass.
|
|
123
|
+
3. After an edit to a file that a feature's `paths` match, a command that touches the app fails with
|
|
124
|
+
`doctor-required`. A read-only target, if the repo has one, refuses one write with `read-only`.
|
|
125
|
+
4. The whole report is in the description of the PR that adds the CLI. The gate reads the report
|
|
126
|
+
from the HTML comment at the report's end.
|
|
127
|
+
|
|
128
|
+
## Maintain
|
|
129
|
+
|
|
130
|
+
Wire these into the repo, as [Maintain](./references/maintain.md) shows:
|
|
131
|
+
|
|
132
|
+
- **The gate on each PR.** A PR that touches a feature's `paths` needs a verdict for its code.
|
|
133
|
+
- **`lint` in CI.** It needs no running app.
|
|
134
|
+
- **A journey fixed with its feature.** A PR that changes a feature fixes the feature's journey.
|
|
135
|
+
|
|
136
|
+
Add no scheduled job. The gate checks a feature each time a PR changes it.
|
|
137
|
+
|
|
138
|
+
**Reply:** the PR link, and for each prove step, the command and the output lines that show it held.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Create
|
|
2
|
+
|
|
3
|
+
Add the verify CLI, its registry and the repo's `verify` skill. The registry is the file that
|
|
4
|
+
declares the targets, drivers, actions, repo commands, doctor checks and features;
|
|
5
|
+
[`verify-registry.ts`](../template/verify-registry.ts) shows one of each, on the builder that
|
|
6
|
+
`createWringer` returns.
|
|
7
|
+
|
|
8
|
+
The mistakes that cost the most:
|
|
9
|
+
|
|
10
|
+
- **Leaving a read unmarked.** A repo command is a write unless it declares `effect: 'read'`, and an
|
|
11
|
+
action must declare its effect. A read-only target refuses each write with exit code 3.
|
|
12
|
+
- **A glob relative to a package.** Write each feature's `paths` globs relative to the repo root, as
|
|
13
|
+
`git ls-files` prints paths. In a monorepo, a glob relative to a package folder matches nothing.
|
|
14
|
+
- **A placeholder in a journey.** In the `verify` skill's fenced code blocks, `bun verify lint`
|
|
15
|
+
parses each line that starts with `bun verify`, and reads `<name>` as a shell redirect. Write each
|
|
16
|
+
such line as a command that runs, and put a command with a placeholder in inline code.
|
|
17
|
+
- **Matching a plain-text ready line as a string.** The launch target's `ready` function gets a JSON
|
|
18
|
+
object line as that object, and any other line as `{ message: <the line> }`. Match plain text on
|
|
19
|
+
`line['message']`.
|
|
20
|
+
|
|
21
|
+
## Steps
|
|
22
|
+
|
|
23
|
+
1. Install each driver the app needs, at an exact version, such as
|
|
24
|
+
`bun add --dev --exact @wringer/http`. Expect: each one in `devDependencies`.
|
|
25
|
+
|
|
26
|
+
| Driver | Drives |
|
|
27
|
+
| ------------------ | -------------------------------------------- |
|
|
28
|
+
| `@wringer/browser` | a page, through its accessibility tree |
|
|
29
|
+
| `@wringer/http` | the app's HTTP API |
|
|
30
|
+
| `@wringer/db` | SQL on the app's SQLite or Postgres database |
|
|
31
|
+
| `@wringer/stream` | the app's logs, recorded for the whole run |
|
|
32
|
+
|
|
33
|
+
Each driver adds its own commands and its own doctor check. Its README in `node_modules/` gives
|
|
34
|
+
its config for a target.
|
|
35
|
+
|
|
36
|
+
2. Add `.wringer/` to `.gitignore`. The CLI keeps each run's state and evidence there.
|
|
37
|
+
3. Copy [`verify.ts`](../template/verify.ts) and
|
|
38
|
+
[`verify-registry.ts`](../template/verify-registry.ts) into `scripts/verify/`. Add
|
|
39
|
+
`"verify": "bun scripts/verify/verify.ts"` to the `scripts` of `package.json`. Expect:
|
|
40
|
+
`bun verify --help` lists the template's commands.
|
|
41
|
+
4. In `verify-registry.ts`, write the `local` target with `mode: 'launch'` and
|
|
42
|
+
`access: 'read-write'`. Its `launch` function returns:
|
|
43
|
+
- `command`: the command a developer runs to start the app;
|
|
44
|
+
- `env`: the app's environment. Point the app's state at `ctx.runDirectory` here, such as a
|
|
45
|
+
SQLite file, so each run starts clean. For a database server, name a database per run;
|
|
46
|
+
- `ready`: a function that returns the app's endpoints once a line shows the app is ready, such
|
|
47
|
+
as `{ web: 'http://127.0.0.1:4100' }`, and `null` before. The drivers use the `web` endpoint
|
|
48
|
+
unless a driver's config sets another `endpoint`.
|
|
49
|
+
5. Write a target with `mode: 'attach'` for each instance that runs apart from the CLI, such as a
|
|
50
|
+
staging or a production deployment. Its `endpoints` function returns the instance's URLs. Give a
|
|
51
|
+
target `access: 'read-only'` when agents must never write there, such as production, and a
|
|
52
|
+
`refusalHint` that tells the agent where to report a write it needed.
|
|
53
|
+
6. Under each target's `drivers`, give a config for each driver the target allows. A target with no
|
|
54
|
+
config for a driver refuses that driver's commands.
|
|
55
|
+
7. Write an action with `.action` for each setup step a journey needs and a user can't do quickly in
|
|
56
|
+
the app, such as seeding a record. The CLI runs it as `bun verify action <name>`.
|
|
57
|
+
8. Write a repo command with `.command` for a read that a journey checks, such as a count.
|
|
58
|
+
9. Write a doctor check with `.check` for each thing that must hold before a journey means anything,
|
|
59
|
+
such as an API that answers. Then run `bun verify up`, then `bun verify doctor`. Expect:
|
|
60
|
+
`data.passed: true`. Run `bun verify down`.
|
|
61
|
+
10. Write 3 to 5 features with `.feature`, each with `name`, `summary` and `paths`. Pick the
|
|
62
|
+
journeys users take most, from the app's routes and its README, and give each feature the globs
|
|
63
|
+
of the files that change its behaviour.
|
|
64
|
+
11. Copy [`template/verify/`](../template/verify/) to `.claude/skills/verify/`. Rewrite the
|
|
65
|
+
frontmatter's `name` and `description` and the `#` title for the app. Set
|
|
66
|
+
`metadata.wringer-command` to the command that runs the script, `bun verify` by default. Rewrite
|
|
67
|
+
each `<!-- repo: <part> -->` block:
|
|
68
|
+
- `targets`: one row per target, with the command that starts a run, and what to do on a
|
|
69
|
+
refusal.
|
|
70
|
+
- `commands`: what `--help` can't say about the actions and repo commands, such as the order to
|
|
71
|
+
run them in.
|
|
72
|
+
- `registry`: the path of the registry file.
|
|
73
|
+
|
|
74
|
+
Then rewrite `references/feature-map.md` with one `##` entry per feature, in the template's
|
|
75
|
+
form: what it does, how a user reaches it, its journey as a block of commands that run as
|
|
76
|
+
written, and its end state.
|
|
77
|
+
|
|
78
|
+
12. Run `bun verify lint`. Expect: `ok: true`, and `data.commands`, the count of journey lines it
|
|
79
|
+
parsed, above 0. A count of 0 means it found no journey.
|
|
80
|
+
13. Run `bun verify --help`, then `bun verify <group> --help` for each group it lists, such as
|
|
81
|
+
`action`. Expect: every action and repo command, each marked `[read]` or `[write]`.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Fresh subagent brief
|
|
2
|
+
|
|
3
|
+
Send the brief below to a new general-purpose subagent. Never use a fork: a fork carries your
|
|
4
|
+
context, and the subagent must know only what the repo's `verify` skill tells it. Fill in the three
|
|
5
|
+
placeholders, and add nothing else. A fact you add about the app or the CLI hides a gap in the
|
|
6
|
+
skill.
|
|
7
|
+
|
|
8
|
+
- `<repo root>`: the absolute path of the repo.
|
|
9
|
+
- `<skill path>`: the absolute path of the `SKILL.md` of the repo's `verify` skill.
|
|
10
|
+
- `<features>`: every feature name that `bun verify features` lists, comma-separated.
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
Load the skill at <skill path> and read it whole. It tells you how to use this repo's app with
|
|
14
|
+
its verify CLI.
|
|
15
|
+
|
|
16
|
+
Your task: for each of these features, run the CLI's `done` command and get exit code 0:
|
|
17
|
+
<features>.
|
|
18
|
+
|
|
19
|
+
- Use only what the skill says and what the CLI prints, `--help` included. Read no source code.
|
|
20
|
+
- Run every command from the repo root, <repo root>.
|
|
21
|
+
- Leave the app's code and the skill unchanged.
|
|
22
|
+
- When you finish, stop the app with the command the skill gives.
|
|
23
|
+
|
|
24
|
+
Reply with:
|
|
25
|
+
1. For each feature: each command you ran, its exit code, and the `ok`, `feature` and
|
|
26
|
+
`data.fingerprint` fields of the JSON that `done` printed.
|
|
27
|
+
2. Each place where the skill left you to guess, was wrong, or sent you to the source: the line of
|
|
28
|
+
the skill, what you needed, and what you did instead. Write "none" when there was none.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
When the subagent names a gap, fix the `verify` skill, or the CLI when its help or an error caused
|
|
32
|
+
the gap. Then send the same brief to a new subagent. When a `done` fails and the subagent names no
|
|
33
|
+
gap, find the cause before you change the skill: the app or the registry may be wrong. Stop when one
|
|
34
|
+
subagent gets exit code 0 from `done` on every feature and names no gap.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Maintain
|
|
2
|
+
|
|
3
|
+
Wire `bun verify lint` and the gate into the repo's CI, fix a journey when its feature changes, and
|
|
4
|
+
upgrade the `verify` skill when `lint` reports an older template.
|
|
5
|
+
|
|
6
|
+
The mistakes that cost the most:
|
|
7
|
+
|
|
8
|
+
- **A shallow checkout.** The gate needs the merge base with the PR's base branch, so it fails on a
|
|
9
|
+
checkout without the full history.
|
|
10
|
+
- **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 the report an author pastes later.
|
|
12
|
+
- **A nested copy.** `cp -R` into a folder that exists nests the copy inside it. Move the old
|
|
13
|
+
`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
|
+
|
|
17
|
+
## Wire the checks into CI
|
|
18
|
+
|
|
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 maps the PR's changed files to features
|
|
21
|
+
through `paths`, reads the last report block in the body, and works out the code's fingerprint
|
|
22
|
+
itself. It fails with exit code 1 when a changed feature has no verdict, or a verdict for other
|
|
23
|
+
code.
|
|
24
|
+
|
|
25
|
+
Add a workflow like this one. When the repo's other workflows pin each action to a commit SHA, pin
|
|
26
|
+
these the same way.
|
|
27
|
+
|
|
28
|
+
```yaml
|
|
29
|
+
on:
|
|
30
|
+
pull_request:
|
|
31
|
+
types: [opened, synchronize, reopened, edited]
|
|
32
|
+
jobs:
|
|
33
|
+
verify:
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@v4
|
|
37
|
+
with:
|
|
38
|
+
fetch-depth: 0 # the gate needs the merge base
|
|
39
|
+
- uses: oven-sh/setup-bun@v2
|
|
40
|
+
- run: bun install --frozen-lockfile
|
|
41
|
+
- run: bun verify lint
|
|
42
|
+
- run: jq -r '.pull_request.body // ""' "$GITHUB_EVENT_PATH" > "$RUNNER_TEMP/pr-body.md"
|
|
43
|
+
- run: bun verify gate --base "origin/$GITHUB_BASE_REF" --body-file "$RUNNER_TEMP/pr-body.md"
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Keep it a workflow of its own, so a body edit reruns only this job.
|
|
47
|
+
|
|
48
|
+
## Fix a drifted journey
|
|
49
|
+
|
|
50
|
+
A journey breaks when a change to its feature, such as a renamed button, makes a command of its
|
|
51
|
+
journey fail, or leaves the app different from the end state the journey expects. Fix the feature's
|
|
52
|
+
journey in the `verify` skill's `references/feature-map.md`, in the same PR. Then follow the
|
|
53
|
+
`verify` skill's "Check a change" for that feature. Replace the whole report in the PR body with the
|
|
54
|
+
new output of `bun verify report --human`.
|
|
55
|
+
|
|
56
|
+
## Upgrade the template
|
|
57
|
+
|
|
58
|
+
When `lint` reports that the skill follows an older template:
|
|
59
|
+
|
|
60
|
+
1. Run `bunx @wringer/gunshi skill install`, as [Install the skill](../SKILL.md#install-the-skill)
|
|
61
|
+
shows. It replaces the repo's copy of the wringer skill.
|
|
62
|
+
2. Move the repo's `verify` skill folder, such as `.claude/skills/verify/`, to a folder outside
|
|
63
|
+
`.claude/skills/`, so it doesn't load as a second skill. List that folder in `.git/info/exclude`,
|
|
64
|
+
so git ignores it without a change to `.gitignore`.
|
|
65
|
+
3. Copy `.claude/skills/wringer/template/verify/` to the folder that `runVerify`'s `skill` option
|
|
66
|
+
names, which no longer exists.
|
|
67
|
+
4. Copy the old skill's `references/feature-map.md` over the template's. Copy the frontmatter's
|
|
68
|
+
`name`, `description` and `metadata.wringer-command`, the `#` title, and each `<!-- repo -->`
|
|
69
|
+
block, from the old `SKILL.md` into the new one. When the new template renames or adds a block,
|
|
70
|
+
fill it from the old skill's matching content.
|
|
71
|
+
5. Read the release notes of each `@wringer/gunshi` version since the old one on
|
|
72
|
+
<https://github.com/zgeoff/wringer/releases>. Apply what they ask of the `<!-- repo -->` blocks,
|
|
73
|
+
`verify.ts` and the registry.
|
|
74
|
+
6. Run `bun verify lint`. Expect: `ok: true`. Then delete the old skill.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Prove
|
|
2
|
+
|
|
3
|
+
Prove that the verify CLI, its registry and the repo's `verify` skill work before you open the PR
|
|
4
|
+
that adds them.
|
|
5
|
+
|
|
6
|
+
- Make every change to the code, the registry and the `verify` skill before step 2. A verdict holds
|
|
7
|
+
for the code as it was at `done`: an edit makes it stale, and undoing the edit makes it hold
|
|
8
|
+
again.
|
|
9
|
+
- When a fresh subagent names a gap, follow the brief. When another step fails because the `verify`
|
|
10
|
+
skill, the registry or the CLI code is wrong, fix it, and start again at step 1.
|
|
11
|
+
- For each step, put its command and the output lines its "Expect" lists in the PR description,
|
|
12
|
+
under `## Verification`. Add the heading when the PR template lacks it.
|
|
13
|
+
|
|
14
|
+
## Steps
|
|
15
|
+
|
|
16
|
+
1. Run `bun verify up`, then `bun verify doctor`. Expect: the doctor's last JSON line has `ok: true`
|
|
17
|
+
and `data.passed: true`. Then run `bun verify down`.
|
|
18
|
+
2. Send the [fresh subagent brief](./fresh-subagent-brief.md) to a new subagent, and follow that
|
|
19
|
+
reference until one subagent reaches `done` on every feature and names no gap. Expect: its reply,
|
|
20
|
+
with exit code 0 from each `done`. Put the subagent's result for each `done` in the PR: the
|
|
21
|
+
feature, the exit code, `ok` and `data.fingerprint`.
|
|
22
|
+
3. Check that the CLI refuses to run against a changed tree:
|
|
23
|
+
1. Run `bun verify up`, then `bun verify doctor`. Expect: `data.passed: true`.
|
|
24
|
+
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 map, run one command that touches
|
|
26
|
+
the app, such as an `action` or a `browser` command. Expect: exit code 3 and `error.code`
|
|
27
|
+
`doctor-required`.
|
|
28
|
+
4. Undo the edit, and run `bun verify down`.
|
|
29
|
+
4. When the Targets section of the `verify` skill lists a read-only target, check that it refuses a
|
|
30
|
+
write. Skip this step when it lists none.
|
|
31
|
+
1. Start the instance the target attaches to, as the skill says. Use an instance you may lose
|
|
32
|
+
data on, in case the refusal is broken.
|
|
33
|
+
2. Run `bun verify use --target <target>`, then `bun verify attach`, then `bun verify doctor`.
|
|
34
|
+
3. Run one command that `--help` marks `[write]`, such as a write action. Expect: exit code 3 and
|
|
35
|
+
`error.code` `read-only`.
|
|
36
|
+
4. Run `bun verify detach`, then `bun verify use --target local`.
|
|
37
|
+
5. Run `bun verify report --human`. Expect: each feature whose `paths` match a file the branch
|
|
38
|
+
changes shows `verified`, and every other feature shows `unchanged`. Paste the whole output into
|
|
39
|
+
the PR description as it is, outside a code block. The gate reads the report from the HTML
|
|
40
|
+
comment at its end.
|