@wringer/gunshi 0.1.1 → 0.3.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/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 +36 -23
- package/{skills/wringer/references → guide}/fresh-subagent-brief.md +2 -0
- package/guide/maintain.md +85 -0
- package/guide/overview.md +135 -0
- package/{skills/wringer/references → guide}/prove.md +16 -11
- 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 -0
- 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 -138
- package/skills/wringer/references/maintain.md +0 -74
- package/skills/wringer/template/verify/SKILL.md +0 -175
- 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
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { collectEnvSecrets, createSecretSet, scrubFailure } from '@wringer/core';
|
|
2
|
+
import type { Wringer } from '@wringer/core';
|
|
3
|
+
import type { ParsedInvocation } from './pick-cli-outcome.ts';
|
|
4
|
+
|
|
5
|
+
// A parse failure can quote the arguments the person typed, such as an unknown command followed by
|
|
6
|
+
// a header, so its error passes through the secrets of the registry and the environment.
|
|
7
|
+
export function scrubParsedInvocation(
|
|
8
|
+
parsed: ParsedInvocation,
|
|
9
|
+
wringer: Wringer,
|
|
10
|
+
env: Readonly<Record<string, string | undefined>>,
|
|
11
|
+
): ParsedInvocation {
|
|
12
|
+
if (parsed.kind !== 'failed') {
|
|
13
|
+
return parsed;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const secrets = createSecretSet();
|
|
17
|
+
|
|
18
|
+
for (const secret of collectEnvSecrets({ declared: wringer.secrets, env })) {
|
|
19
|
+
try {
|
|
20
|
+
secrets.add(secret);
|
|
21
|
+
} catch {
|
|
22
|
+
// A declared value that is too short is reported by the command that runs next. The other
|
|
23
|
+
// secrets still scrub this error.
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
return {
|
|
28
|
+
...parsed,
|
|
29
|
+
command: secrets.scrubText(parsed.command),
|
|
30
|
+
error: scrubFailure(parsed.error, secrets) ?? parsed.error,
|
|
31
|
+
};
|
|
32
|
+
}
|
package/src/wringer-gunshi.ts
CHANGED
|
@@ -1,27 +1,10 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
2
|
+
import { buildGuidePorts } from './build-guide-ports.ts';
|
|
3
|
+
import { buildGuideWringer } from './build-guide-wringer.ts';
|
|
4
|
+
import { runWringer } from './run-verify.ts';
|
|
5
5
|
|
|
6
|
-
const
|
|
7
|
-
const
|
|
6
|
+
const [, script] = process.argv;
|
|
7
|
+
const selfCommand = script === undefined ? [process.execPath] : [process.execPath, script];
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
process.exit(2);
|
|
12
|
-
}
|
|
13
|
-
|
|
14
|
-
const destination = resolve(args.destination);
|
|
15
|
-
|
|
16
|
-
const result = await writeSkillCopy({
|
|
17
|
-
source: join(import.meta.dir, '..', 'skills', 'wringer'),
|
|
18
|
-
destination,
|
|
19
|
-
cwd: process.cwd(),
|
|
20
|
-
});
|
|
21
|
-
|
|
22
|
-
if (!result.ok) {
|
|
23
|
-
console.error(`Refused: ${result.reason} Pass --dir with the folder for the wringer skill.`);
|
|
24
|
-
process.exit(2);
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
console.log(`Installed the wringer skill to ${destination}`);
|
|
9
|
+
// `guide` reads only the installed package, so it runs from any folder, in a repo or not.
|
|
10
|
+
await runWringer(buildGuideWringer(), buildGuidePorts(selfCommand));
|
|
@@ -1,8 +0,0 @@
|
|
|
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;
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export declare const templateVersion = 1;
|
|
@@ -1,12 +0,0 @@
|
|
|
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/skills/wringer/SKILL.md
DELETED
|
@@ -1,138 +0,0 @@
|
|
|
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.
|
|
@@ -1,74 +0,0 @@
|
|
|
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.
|
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: verify
|
|
3
|
-
description:
|
|
4
|
-
'Uses the Larder app the way a user would with `bun verify`, and records the verdict that a
|
|
5
|
-
feature works. Load it before you check a change in the running app, run a journey from the
|
|
6
|
-
feature map, or put the verdicts in a PR.'
|
|
7
|
-
metadata:
|
|
8
|
-
wringer-template: 1
|
|
9
|
-
wringer-command: bun verify
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
# Verify Larder
|
|
13
|
-
|
|
14
|
-
Use `bun verify` to start the app, use each feature your change touches the way a user would, and
|
|
15
|
-
record a verdict that it works. Hand back the output of `bun verify report --human` and each feature
|
|
16
|
-
you could not verify. The CI gate, `bun verify gate`, fails a PR that changes a feature with no
|
|
17
|
-
verdict.
|
|
18
|
-
|
|
19
|
-
Each feature in the [feature map](./references/feature-map.md) has a journey: the `bun verify`
|
|
20
|
-
commands that use the feature, and the end state that shows it works.
|
|
21
|
-
|
|
22
|
-
The mistakes that cost the most time:
|
|
23
|
-
|
|
24
|
-
- **Using the app before `doctor` passes.** `bun verify doctor` checks that the app answers and that
|
|
25
|
-
each driver works. Until it passes on the current run, the one that `up` or `attach` started, any
|
|
26
|
-
command that touches the app fails with exit code 3.
|
|
27
|
-
- **Editing the app's code while `up` runs it.** The next command that touches the app fails with
|
|
28
|
-
`doctor-required`. Run `bun verify up --restart`, then `bun verify doctor`. Then run the feature's
|
|
29
|
-
journey again.
|
|
30
|
-
- **Running `done` before you check the end state.** `done` checks only that one command of the
|
|
31
|
-
feature's journey after `use --feature`, a read or a write, succeeded. It does not check the
|
|
32
|
-
result. Check the end state yourself first.
|
|
33
|
-
- **Branching on the error message.** Branch on the exit code and `error.code`. The message text can
|
|
34
|
-
change in any release.
|
|
35
|
-
|
|
36
|
-
## Key rules
|
|
37
|
-
|
|
38
|
-
- [Check a change](#check-a-change): report, start a run, doctor, then run the journey, check the
|
|
39
|
-
end state and `done` for each feature, then report again and end the run.
|
|
40
|
-
- [Read the envelope](#read-the-envelope): one JSON object per command, and an exit code to branch
|
|
41
|
-
on.
|
|
42
|
-
- [Targets](#targets): the targets this repo declares; check a change on one that `up` starts.
|
|
43
|
-
- [Commands](#commands): `bun verify --help` lists every command, each marked read or write.
|
|
44
|
-
- [Feature map](#feature-map): the file that holds each feature's journey and end state.
|
|
45
|
-
- [Update the feature map](#update-the-feature-map): fix a broken journey in the same PR, and run
|
|
46
|
-
`lint`.
|
|
47
|
-
|
|
48
|
-
## References
|
|
49
|
-
|
|
50
|
-
- [Feature map](./references/feature-map.md): each feature's journey and end state, before you check
|
|
51
|
-
the feature.
|
|
52
|
-
|
|
53
|
-
## Check a change
|
|
54
|
-
|
|
55
|
-
1. Run `bun verify report`. Each feature in `data.report.features` with `changed: true` has a file
|
|
56
|
-
under its `paths` that differs from the default branch, committed or not. Each one needs a
|
|
57
|
-
verdict.
|
|
58
|
-
2. Unless your task names another target, start a run on `local`, with the commands in the
|
|
59
|
-
[Targets](#targets) table. Expect: `ok: true`, and the app's endpoints in `data.endpoints`.
|
|
60
|
-
3. Run `bun verify doctor`. Expect: `data.passed: true`. When a check fails, fix its cause, and run
|
|
61
|
-
`doctor` again.
|
|
62
|
-
4. Run the feature's journey from the [feature map](./references/feature-map.md). Its first line,
|
|
63
|
-
`use --feature`, records each later command under that feature. It does not change the target.
|
|
64
|
-
Expect: each command exits 0.
|
|
65
|
-
5. Compare the app with the feature's end state:
|
|
66
|
-
- When it matches, and no command failed with `read-only`, go on to step 6.
|
|
67
|
-
- When your change broke the feature, fix the app's code. Then run `bun verify up --restart`,
|
|
68
|
-
`bun verify doctor` and the journey again.
|
|
69
|
-
- When your change means to change the end state, fix the feature's entry in the feature map, and
|
|
70
|
-
run `bun verify lint`. Then run the journey again.
|
|
71
|
-
- Otherwise, skip `done` for this feature. List it in your reply with the end state you expected
|
|
72
|
-
and the `data` you got.
|
|
73
|
-
6. Run `bun verify done`. It records a verdict for the feature that `use --feature` set. Expect:
|
|
74
|
-
`ok: true`. It fails with exit code 1 and `check-failed` until one command of the journey
|
|
75
|
-
succeeds after `use --feature` and `doctor`.
|
|
76
|
-
7. Repeat steps 4 to 6 for each feature with `changed: true`, and for each feature your task names,
|
|
77
|
-
in the order the feature map lists them. When the feature map's opening names a journey to run
|
|
78
|
-
last, follow it. When a changed feature has no entry in the feature map, write one, and run
|
|
79
|
-
`bun verify lint`.
|
|
80
|
-
8. Run `bun verify report --human`. A changed feature with your verdict shows `verified`; a feature
|
|
81
|
-
the branch doesn't change shows `unchanged`, with your verdict's evidence. After `done`, an edit
|
|
82
|
-
to any file on the branch makes every verdict `stale`, unless you commit the same code. Repeat
|
|
83
|
-
steps 4 to 6 for each stale feature.
|
|
84
|
-
9. Put the whole output in the PR body, in place of the output of an older `report --human`. Keep
|
|
85
|
-
the HTML comment at the end of the output: the gate reads the report from it.
|
|
86
|
-
10. End the run: `bun verify down` after `up`, or `bun verify detach` after `attach`.
|
|
87
|
-
|
|
88
|
-
## Read the envelope
|
|
89
|
-
|
|
90
|
-
Each command prints one JSON envelope as its last line. With `--human`, it prints text for a person
|
|
91
|
-
in its place. A streaming command, such as `doctor`, prints its events as JSON lines before the
|
|
92
|
-
envelope. Read these fields:
|
|
93
|
-
|
|
94
|
-
- `ok`, then `data` on success, or `error.code`, `error.message` and `error.hint` on failure;
|
|
95
|
-
- `evidence`: the files the command kept, under `.wringer/`;
|
|
96
|
-
- `truncated` and `truncatedPath`: `data` was too large, and the file at `truncatedPath` holds it.
|
|
97
|
-
|
|
98
|
-
| Exit | `error.code` | Do |
|
|
99
|
-
| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
|
|
100
|
-
| 0 | none | Go on. |
|
|
101
|
-
| 1 | `check-failed` | Read the evidence, then go on as step 5 says. |
|
|
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`, fix the problem on this machine, 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`. Then report it. |
|
|
110
|
-
|
|
111
|
-
## Targets
|
|
112
|
-
|
|
113
|
-
Start a launch target's app with `bun verify up`, and stop it with `bun verify down`. Connect to an
|
|
114
|
-
attach target with `bun verify attach`: an attach target is an app that runs apart from
|
|
115
|
-
`bun verify`, and `bun verify detach` leaves it running. Your edits never reach an attach target's
|
|
116
|
-
app, so check a change on a launch target.
|
|
117
|
-
|
|
118
|
-
Run `bun verify use --target <target>` to point every later command at a target. `--target` on one
|
|
119
|
-
command points that command alone.
|
|
120
|
-
|
|
121
|
-
<!-- repo: targets -->
|
|
122
|
-
|
|
123
|
-
| Target | Start with | Access | Notes |
|
|
124
|
-
| -------- | ---------------------------------------------------------- | ---------- | ------------------------------------------------------ |
|
|
125
|
-
| `local` | `bun verify use --target local`, then `bun verify up` | read-write | Starts the app with `bun run dev`. |
|
|
126
|
-
| `shared` | `bun verify use --target shared`, then `bun verify attach` | read-only | An app that `bun verify` did not start. Never stop it. |
|
|
127
|
-
|
|
128
|
-
<!-- /repo -->
|
|
129
|
-
|
|
130
|
-
## Commands
|
|
131
|
-
|
|
132
|
-
Run `bun verify --help` for the list, and `bun verify <command> --help` for a command's flags. The
|
|
133
|
-
help marks each command `[read]` or `[write]`.
|
|
134
|
-
|
|
135
|
-
- Run `bun verify <group> --help` to list the commands in a group, such as `action`. The top-level
|
|
136
|
-
list shows the group alone.
|
|
137
|
-
- Write a negative number with `=`, as in `--offset=-5`.
|
|
138
|
-
- Pass an object as JSON text, as in `--filter '{"shelf":"top"}'`.
|
|
139
|
-
|
|
140
|
-
<!-- repo: commands -->
|
|
141
|
-
|
|
142
|
-
- `bun verify action add-item --name <name>` adds an item through the API.
|
|
143
|
-
- `bun verify items count` counts the items through the API, in `data.count`.
|
|
144
|
-
|
|
145
|
-
<!-- /repo -->
|
|
146
|
-
|
|
147
|
-
## Feature map
|
|
148
|
-
|
|
149
|
-
Before you run a feature's journey, read its entry in the
|
|
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`. When a PR changes a file that they
|
|
152
|
-
match, the gate needs a verdict for the feature.
|
|
153
|
-
|
|
154
|
-
## Update the feature map
|
|
155
|
-
|
|
156
|
-
<!-- repo: registry -->
|
|
157
|
-
|
|
158
|
-
The registry, `scripts/verify/verify-registry.ts`, declares the targets, actions, commands, doctor
|
|
159
|
-
checks and features, with each feature's `paths`.
|
|
160
|
-
|
|
161
|
-
<!-- /repo -->
|
|
162
|
-
|
|
163
|
-
- When a feature's journey stops working because the feature changed, fix it in the same PR.
|
|
164
|
-
- In this file, edit only the frontmatter's `name` and `description`, the `#` title, and the lines
|
|
165
|
-
inside the `<!-- repo -->` blocks. An upgrade of the template keeps those and replaces every other
|
|
166
|
-
line. You may edit any line of the feature map.
|
|
167
|
-
- After you change this skill, its feature map or the registry, run `bun verify lint`. It fails on:
|
|
168
|
-
- a `paths` glob that matches no file;
|
|
169
|
-
- a command in a code block that would fail before it ran, such as one with an unknown flag,
|
|
170
|
-
feature or target;
|
|
171
|
-
- a skill written from an older template. Load the `wringer` skill that `@wringer/gunshi` ships,
|
|
172
|
-
and follow its upgrade steps.
|
|
173
|
-
|
|
174
|
-
**Reply:** the output of `bun verify report --human`, and each feature you could not verify, with
|
|
175
|
-
the command that failed and its `error.code`, or the end state you expected and the `data` you got.
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
# Feature map
|
|
2
|
-
|
|
3
|
-
## add-item
|
|
4
|
-
|
|
5
|
-
- **What:** a user adds an item to the pantry.
|
|
6
|
-
- **How a user reaches it:** open `/pantry`, type a name, and press Add.
|
|
7
|
-
- **Journey:**
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
bun verify use --feature add-item
|
|
11
|
-
bun verify items count
|
|
12
|
-
bun verify action add-item --name Oats
|
|
13
|
-
bun verify items count
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
- **End state:** the second `items count` returns one more item than the first. Run
|
|
17
|
-
`bun verify http request --path /api/items` too: its `data.json` lists `Oats`.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
import { WringerError } from '@wringer/core';
|
|
2
|
-
import type { Wringer } from '@wringer/core';
|
|
3
|
-
import { buildLintCommand } from './build-lint-command.ts';
|
|
4
|
-
|
|
5
|
-
// The registry with the `lint` built-in added. `lint` parses journey lines with gunshi, so this
|
|
6
|
-
// package adds it rather than core.
|
|
7
|
-
export function buildLintedWringer(wringer: Wringer, skillFolder: string): Wringer {
|
|
8
|
-
const lint = buildLintCommand(skillFolder);
|
|
9
|
-
const key = lint.info.path.join(' ');
|
|
10
|
-
|
|
11
|
-
if (wringer.commands.has(key)) {
|
|
12
|
-
throw new WringerError('usage', { message: `Two commands share the name \`${key}\`.` });
|
|
13
|
-
}
|
|
14
|
-
|
|
15
|
-
return Object.freeze({ ...wringer, commands: new Map([...wringer.commands, [key, lint]]) });
|
|
16
|
-
}
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
import { isAbsolute, relative } from 'node:path';
|
|
2
|
-
|
|
3
|
-
export type DestinationState = 'absent' | 'wringer-skill' | 'other';
|
|
4
|
-
|
|
5
|
-
export interface SkillCopyPlan {
|
|
6
|
-
readonly source: string;
|
|
7
|
-
readonly destination: string;
|
|
8
|
-
readonly cwd: string;
|
|
9
|
-
readonly state: DestinationState;
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
// Why the installer must not remove the destination, or null when it may. The install removes the
|
|
13
|
-
// destination before it copies, so a wrong `--dir` would delete another skill or the repo.
|
|
14
|
-
export function findSkillCopyRefusal(plan: SkillCopyPlan): string | null {
|
|
15
|
-
if (isInside(plan.destination, plan.cwd)) {
|
|
16
|
-
return `${plan.destination} holds the current folder.`;
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
if (isInside(plan.destination, plan.source) || isInside(plan.source, plan.destination)) {
|
|
20
|
-
return `${plan.destination} overlaps the packaged skill.`;
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
if (plan.state === 'other') {
|
|
24
|
-
return `${plan.destination} exists and is not a copy of the wringer skill.`;
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
return null;
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
function isInside(parent: string, child: string): boolean {
|
|
31
|
-
const path = relative(parent, child);
|
|
32
|
-
|
|
33
|
-
return path === '' || (!path.startsWith('..') && !isAbsolute(path));
|
|
34
|
-
}
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
import { parseArgs } from 'node:util';
|
|
2
|
-
|
|
3
|
-
// Users type `--dir`; the naming lint rejects `dir` as a literal key, so the name lives in a value.
|
|
4
|
-
const directoryFlag = 'dir';
|
|
5
|
-
const defaultDestination = '.claude/skills/wringer';
|
|
6
|
-
|
|
7
|
-
// Answers the destination folder, or null when the arguments are not `skill install [--dir <path>]`.
|
|
8
|
-
export function parseSkillInstallArgs(argv: readonly string[]): { destination: string } | null {
|
|
9
|
-
try {
|
|
10
|
-
const parsed = parseArgs({
|
|
11
|
-
args: [...argv],
|
|
12
|
-
options: { [directoryFlag]: { type: 'string' } },
|
|
13
|
-
allowPositionals: true,
|
|
14
|
-
strict: true,
|
|
15
|
-
});
|
|
16
|
-
|
|
17
|
-
if (parsed.positionals.join(' ') !== 'skill install') {
|
|
18
|
-
return null;
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
return { destination: parsed.values[directoryFlag] ?? defaultDestination };
|
|
22
|
-
} catch {
|
|
23
|
-
return null;
|
|
24
|
-
}
|
|
25
|
-
}
|
package/src/template-version.ts
DELETED