@wringer/gunshi 0.1.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
|
@@ -0,0 +1,175 @@
|
|
|
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.
|
|
@@ -0,0 +1,17 @@
|
|
|
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`.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { createWringer, local } from '@wringer/core';
|
|
2
|
+
import type { Wringer } from '@wringer/core';
|
|
3
|
+
import { http } from '@wringer/http';
|
|
4
|
+
import { z } from 'zod';
|
|
5
|
+
|
|
6
|
+
const itemSchema = z.strictObject({ id: z.number().int(), name: z.string() });
|
|
7
|
+
|
|
8
|
+
// The verify registry of an example app, Larder, which lists the items in a pantry. Replace each
|
|
9
|
+
// target, action, command, check and feature with the repo's own; keep the shape.
|
|
10
|
+
export function createVerifyRegistry(): Wringer {
|
|
11
|
+
return createWringer({ name: 'larder' })
|
|
12
|
+
.use(http({}))
|
|
13
|
+
.target('local', {
|
|
14
|
+
mode: 'launch',
|
|
15
|
+
access: 'read-write',
|
|
16
|
+
host: local(),
|
|
17
|
+
launch: () => ({
|
|
18
|
+
command: ['bun', 'run', 'dev'],
|
|
19
|
+
ready: (line) =>
|
|
20
|
+
line['event'] === 'listening'
|
|
21
|
+
? { web: `http://127.0.0.1:${String(line['port'])}` }
|
|
22
|
+
: null,
|
|
23
|
+
}),
|
|
24
|
+
drivers: { http: () => ({ healthPath: '/api/health' }) },
|
|
25
|
+
})
|
|
26
|
+
.target('shared', {
|
|
27
|
+
mode: 'attach',
|
|
28
|
+
access: 'read-only',
|
|
29
|
+
refusalHint:
|
|
30
|
+
'This target is read-only. Leave the write undone, skip `done` for this feature, and report the write you needed.',
|
|
31
|
+
host: local(),
|
|
32
|
+
endpoints: () => ({ web: 'https://larder.example' }),
|
|
33
|
+
drivers: { http: () => ({ healthPath: '/api/health' }) },
|
|
34
|
+
})
|
|
35
|
+
.action({
|
|
36
|
+
name: 'add-item',
|
|
37
|
+
summary: 'Add an item to the pantry through the API',
|
|
38
|
+
effect: 'write',
|
|
39
|
+
input: z.strictObject({ name: z.string().min(1) }),
|
|
40
|
+
data: itemSchema,
|
|
41
|
+
run: async (input, ctx) => {
|
|
42
|
+
const response = await ctx.drivers.http.request({
|
|
43
|
+
method: 'POST',
|
|
44
|
+
path: '/api/items',
|
|
45
|
+
json: input,
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
return itemSchema.parse(response.json);
|
|
49
|
+
},
|
|
50
|
+
})
|
|
51
|
+
.command({
|
|
52
|
+
path: ['items', 'count'],
|
|
53
|
+
summary: 'Count the items in the pantry',
|
|
54
|
+
args: z.strictObject({}),
|
|
55
|
+
data: z.strictObject({ count: z.number().int() }),
|
|
56
|
+
effect: 'read',
|
|
57
|
+
run: async (_args, ctx) => {
|
|
58
|
+
const response = await ctx.drivers.http.request({ path: '/api/items' });
|
|
59
|
+
|
|
60
|
+
return { count: z.array(itemSchema).parse(response.json).length };
|
|
61
|
+
},
|
|
62
|
+
})
|
|
63
|
+
.check({
|
|
64
|
+
name: 'items-api',
|
|
65
|
+
input: z.strictObject({}),
|
|
66
|
+
data: z.null(),
|
|
67
|
+
timeoutMs: 5000,
|
|
68
|
+
run: async (_input, ctx) => {
|
|
69
|
+
const response = await ctx.drivers.http.request({ path: '/api/items' });
|
|
70
|
+
|
|
71
|
+
z.array(itemSchema).parse(response.json);
|
|
72
|
+
|
|
73
|
+
return null;
|
|
74
|
+
},
|
|
75
|
+
})
|
|
76
|
+
.feature({
|
|
77
|
+
name: 'add-item',
|
|
78
|
+
summary: 'Add an item from the pantry page',
|
|
79
|
+
paths: ['src/items/**', 'src/pages/pantry/**'],
|
|
80
|
+
})
|
|
81
|
+
.build();
|
|
82
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { runVerify } from '@wringer/gunshi';
|
|
2
|
+
import { createVerifyRegistry } from './verify-registry.ts';
|
|
3
|
+
|
|
4
|
+
// The repo's verify CLI. The `verify` script in package.json runs this file, so an agent calls
|
|
5
|
+
// `bun verify <command>`. `skill` names the folder of the repo's verify skill, which `lint` checks.
|
|
6
|
+
await runVerify(createVerifyRegistry(), { skill: '.claude/skills/verify' });
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { join } from 'node:path';
|
|
2
|
+
import { WringerError, buildBuiltinCommand } from '@wringer/core';
|
|
3
|
+
import type { BuiltinContext, RegisteredCommand } from '@wringer/core';
|
|
4
|
+
import { z } from 'zod';
|
|
5
|
+
import { collectLintFiles } from './collect-lint-files.ts';
|
|
6
|
+
import { lintFailureSchema, resolveLintFailures } from './resolve-lint-failures.ts';
|
|
7
|
+
import { templateVersion } from './template-version.ts';
|
|
8
|
+
|
|
9
|
+
const lintArgsSchema = z.strictObject({});
|
|
10
|
+
|
|
11
|
+
type LintArgs = z.infer<typeof lintArgsSchema>;
|
|
12
|
+
|
|
13
|
+
const lintDataSchema = z.strictObject({
|
|
14
|
+
skill: z.string(),
|
|
15
|
+
commands: z.number().int().nonnegative(),
|
|
16
|
+
failures: z.array(lintFailureSchema),
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
type LintData = z.infer<typeof lintDataSchema>;
|
|
20
|
+
|
|
21
|
+
// `lint` needs no run, so CI can call it on a fresh checkout.
|
|
22
|
+
export function buildLintCommand(skillFolder: string): RegisteredCommand {
|
|
23
|
+
return buildBuiltinCommand<LintArgs, LintData>({
|
|
24
|
+
path: ['lint'],
|
|
25
|
+
summary: 'Check the feature paths and the verify skill against the CLI, with no running app',
|
|
26
|
+
args: lintArgsSchema,
|
|
27
|
+
data: lintDataSchema,
|
|
28
|
+
effect: 'read',
|
|
29
|
+
needsRun: false,
|
|
30
|
+
needsDoctor: false,
|
|
31
|
+
run: (_args, ctx) => runLint(ctx, skillFolder),
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
async function runLint(ctx: BuiltinContext, skillFolder: string): Promise<LintData> {
|
|
36
|
+
const root = ctx.session.root;
|
|
37
|
+
|
|
38
|
+
const [listed, deleted] = await Promise.all([
|
|
39
|
+
ctx.session.repoHost.runGit({
|
|
40
|
+
cwd: root,
|
|
41
|
+
args: ['ls-files', '-z', '--cached', '--others', '--exclude-standard'],
|
|
42
|
+
}),
|
|
43
|
+
ctx.session.repoHost.runGit({ cwd: root, args: ['ls-files', '-z', '--deleted'] }),
|
|
44
|
+
]);
|
|
45
|
+
|
|
46
|
+
const lintFiles = collectLintFiles({
|
|
47
|
+
listed: listed.stdout,
|
|
48
|
+
deleted: deleted.stdout,
|
|
49
|
+
skillFolder,
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
const skillFiles = await Promise.all(
|
|
53
|
+
lintFiles.skillMarkdown.map(async (path) => ({
|
|
54
|
+
path,
|
|
55
|
+
text: await ctx.session.repoHost.readText(join(root, path)),
|
|
56
|
+
})),
|
|
57
|
+
);
|
|
58
|
+
|
|
59
|
+
const skillPath = `${lintFiles.skillFolder}/SKILL.md`;
|
|
60
|
+
|
|
61
|
+
const result = await resolveLintFailures({
|
|
62
|
+
wringer: ctx.wringer,
|
|
63
|
+
files: lintFiles.files,
|
|
64
|
+
skillPath,
|
|
65
|
+
skillFiles,
|
|
66
|
+
templateVersion,
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
const data = { skill: skillPath, commands: result.commands, failures: [...result.failures] };
|
|
70
|
+
const error = buildLintError(data);
|
|
71
|
+
|
|
72
|
+
if (error !== null) {
|
|
73
|
+
throw error;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
return data;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function buildLintError(data: LintData): WringerError | null {
|
|
80
|
+
if (data.failures.length === 0) {
|
|
81
|
+
return null;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const listedFailures = data.failures.map((failure) => `${failure.where}: ${failure.problem}`);
|
|
85
|
+
|
|
86
|
+
return new WringerError('check-failed', {
|
|
87
|
+
message: `${data.failures.length} lint failure(s). ${listedFailures.join(' ')}`,
|
|
88
|
+
hint: 'Fix each failure in the feature map or the verify skill, then run `lint` again.',
|
|
89
|
+
data,
|
|
90
|
+
});
|
|
91
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
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
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { FeatureDefinition } from '@wringer/core';
|
|
2
|
+
|
|
3
|
+
export interface DeadGlob {
|
|
4
|
+
readonly feature: string;
|
|
5
|
+
readonly glob: string;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
// Each feature's `paths` glob that matches none of the repo's files. A dead glob maps no change to
|
|
9
|
+
// its feature, so the gate never asks for that feature's verdict.
|
|
10
|
+
export function collectDeadGlobs(
|
|
11
|
+
features: readonly FeatureDefinition[],
|
|
12
|
+
files: readonly string[],
|
|
13
|
+
): readonly DeadGlob[] {
|
|
14
|
+
return features.flatMap((feature) =>
|
|
15
|
+
feature.paths.flatMap((glob) => {
|
|
16
|
+
const pattern = new Bun.Glob(glob);
|
|
17
|
+
|
|
18
|
+
return files.some((file) => pattern.match(file)) ? [] : [{ feature: feature.name, glob }];
|
|
19
|
+
}),
|
|
20
|
+
);
|
|
21
|
+
}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import { parseShellWords } from './parse-shell-words.ts';
|
|
2
|
+
|
|
3
|
+
export interface MarkdownFile {
|
|
4
|
+
readonly path: string;
|
|
5
|
+
readonly text: string;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export interface JourneyCommand {
|
|
9
|
+
readonly path: string;
|
|
10
|
+
readonly line: number;
|
|
11
|
+
readonly text: string;
|
|
12
|
+
|
|
13
|
+
// The words after the CLI's own words, or null when the line has an unclosed quote.
|
|
14
|
+
readonly argv: readonly string[] | null;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
// Every line in a fenced code block that calls the CLI, such as `bun verify up` under the words
|
|
18
|
+
// `['bun', 'verify']`. A line may start with a `$ ` prompt and environment assignments. A line
|
|
19
|
+
// that ends in a backslash, or a CLI line with a quote still open, goes on in the next.
|
|
20
|
+
export function collectJourneyCommands(
|
|
21
|
+
files: readonly MarkdownFile[],
|
|
22
|
+
cliWords: readonly string[],
|
|
23
|
+
): readonly JourneyCommand[] {
|
|
24
|
+
return files.flatMap((file) =>
|
|
25
|
+
collectFencedLines(file.text, cliWords).flatMap((fenced) => {
|
|
26
|
+
const command = parseJourneyCommand(fenced.text, cliWords);
|
|
27
|
+
|
|
28
|
+
return command === null ? [] : [{ path: file.path, line: fenced.line, ...command }];
|
|
29
|
+
}),
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
interface FencedLine {
|
|
34
|
+
readonly line: number;
|
|
35
|
+
readonly text: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const openingFencePattern = /^\s*(?<marker>`{3,}|~{3,})/u;
|
|
39
|
+
|
|
40
|
+
// A closing fence holds no info string, so "```ts" inside a block is a line of the block.
|
|
41
|
+
const closingFencePattern = /^\s*(?<marker>`{3,}|~{3,})\s*$/u;
|
|
42
|
+
|
|
43
|
+
function collectFencedLines(text: string, cliWords: readonly string[]): readonly FencedLine[] {
|
|
44
|
+
const fenced: FencedLine[] = [];
|
|
45
|
+
let fence: string | null = null;
|
|
46
|
+
let pending: FencedLine | null = null;
|
|
47
|
+
|
|
48
|
+
for (const [index, line] of text.split(/\r?\n/u).entries()) {
|
|
49
|
+
if (fence === null) {
|
|
50
|
+
fence = openingFencePattern.exec(line)?.groups?.['marker'] ?? null;
|
|
51
|
+
} else if (closingFencePattern.exec(line)?.groups?.['marker']?.startsWith(fence) === true) {
|
|
52
|
+
fence = null;
|
|
53
|
+
|
|
54
|
+
if (pending !== null) {
|
|
55
|
+
fenced.push(toFinishedLine(pending));
|
|
56
|
+
|
|
57
|
+
pending = null;
|
|
58
|
+
}
|
|
59
|
+
} else {
|
|
60
|
+
// An apostrophe in a value, such as `--name O'Brien`, leaves a quote open; the next CLI line
|
|
61
|
+
// starts a new command, so the open line ends there and fails as unclosed.
|
|
62
|
+
if (pending !== null && hasOpenQuote(pending.text, cliWords) && isCLILine(line, cliWords)) {
|
|
63
|
+
fenced.push(pending);
|
|
64
|
+
|
|
65
|
+
pending = null;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
const joined: FencedLine =
|
|
69
|
+
pending === null ? { line: index + 1, text: line } : joinLine(pending, line, cliWords);
|
|
70
|
+
|
|
71
|
+
if (joined.text.endsWith('\\') || hasOpenQuote(joined.text, cliWords)) {
|
|
72
|
+
pending = joined;
|
|
73
|
+
} else {
|
|
74
|
+
pending = null;
|
|
75
|
+
|
|
76
|
+
fenced.push(joined);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// A fence that never closes runs to the end of the file.
|
|
82
|
+
return pending === null ? fenced : [...fenced, toFinishedLine(pending)];
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
// A closing fence ends a continued line, and its last backslash then escapes nothing.
|
|
86
|
+
function toFinishedLine(pending: FencedLine): FencedLine {
|
|
87
|
+
return pending.text.endsWith('\\')
|
|
88
|
+
? { line: pending.line, text: pending.text.slice(0, -1) }
|
|
89
|
+
: pending;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function hasOpenQuote(text: string, cliWords: readonly string[]): boolean {
|
|
93
|
+
return isCLILine(text, cliWords) && parseShellWords(stripPrompt(text)) === null;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// An assignment's value may hold quoted spaces, as in `NOTE='two words' bun verify up`.
|
|
97
|
+
const leadingAssignmentsPattern = /^(?:[A-Za-z_]\w*=(?:'[^']*'|"(?:[^"\\]|\\.)*"|[^\s'"])*\s+)*/u;
|
|
98
|
+
|
|
99
|
+
// A line that calls the CLI, after any prompt and environment assignments. Prose in a code block
|
|
100
|
+
// with an apostrophe, such as "Don't run bun verify up twice", is not one.
|
|
101
|
+
function isCLILine(text: string, cliWords: readonly string[]): boolean {
|
|
102
|
+
const command = stripPrompt(text).replace(leadingAssignmentsPattern, '');
|
|
103
|
+
const prefix = cliWords.join(' ');
|
|
104
|
+
|
|
105
|
+
return command === prefix || command.startsWith(`${prefix} `);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
function stripPrompt(text: string): string {
|
|
109
|
+
return text.trim().replace(/^\$\s+/u, '');
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// Outside quotes the shell drops a backslash and its newline, so the next line goes on in the same
|
|
113
|
+
// word; inside a quote it keeps the newline as part of the word.
|
|
114
|
+
function joinLine(pending: FencedLine, line: string, cliWords: readonly string[]): FencedLine {
|
|
115
|
+
return hasOpenQuote(pending.text, cliWords)
|
|
116
|
+
? { line: pending.line, text: `${pending.text}\n${line}` }
|
|
117
|
+
: { line: pending.line, text: `${pending.text.slice(0, -1)}${line}` };
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const assignmentPattern = /^[A-Za-z_]\w*=/u;
|
|
121
|
+
|
|
122
|
+
function parseJourneyCommand(
|
|
123
|
+
text: string,
|
|
124
|
+
cliWords: readonly string[],
|
|
125
|
+
): Pick<JourneyCommand, 'text' | 'argv'> | null {
|
|
126
|
+
const trimmed = stripPrompt(text);
|
|
127
|
+
const words = parseShellWords(trimmed);
|
|
128
|
+
|
|
129
|
+
if (words === null) {
|
|
130
|
+
return isCLILine(trimmed, cliWords) ? { text: trimmed, argv: null } : null;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
const start = words.findIndex((word) => !assignmentPattern.test(word));
|
|
134
|
+
|
|
135
|
+
if (start === -1 || !cliWords.every((word, index) => words[start + index] === word)) {
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
return { text: trimmed, argv: words.slice(start + cliWords.length) };
|
|
140
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { posix } from 'node:path';
|
|
2
|
+
|
|
3
|
+
export interface LintFileListing {
|
|
4
|
+
// The NUL-separated output of `git ls-files -z --cached --others --exclude-standard`.
|
|
5
|
+
readonly listed: string;
|
|
6
|
+
|
|
7
|
+
// The NUL-separated output of `git ls-files -z --deleted`.
|
|
8
|
+
readonly deleted: string;
|
|
9
|
+
readonly skillFolder: string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export interface LintFiles {
|
|
13
|
+
readonly files: readonly string[];
|
|
14
|
+
readonly skillFolder: string;
|
|
15
|
+
readonly skillMarkdown: readonly string[];
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// The repo's files as `lint` sees them, and the Markdown files of the verify skill among them.
|
|
19
|
+
// `--cached` still lists a tracked file that the working tree has deleted, so those come off.
|
|
20
|
+
export function collectLintFiles(listing: LintFileListing): LintFiles {
|
|
21
|
+
const gone = new Set(listing.deleted.split('\0'));
|
|
22
|
+
|
|
23
|
+
const files = [...new Set(listing.listed.split('\0'))].filter(
|
|
24
|
+
(path) => path !== '' && !gone.has(path),
|
|
25
|
+
);
|
|
26
|
+
|
|
27
|
+
const skillFolder = posix.normalize(listing.skillFolder).replace(/\/+$/u, '');
|
|
28
|
+
|
|
29
|
+
return {
|
|
30
|
+
files,
|
|
31
|
+
skillFolder,
|
|
32
|
+
skillMarkdown: files.filter(
|
|
33
|
+
(path) => path.startsWith(`${skillFolder}/`) && path.endsWith('.md'),
|
|
34
|
+
),
|
|
35
|
+
};
|
|
36
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
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
|
+
}
|
package/src/index.ts
CHANGED