@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,56 @@
|
|
|
1
|
+
const featuresOpenMarker = '<!-- wringer:features -->';
|
|
2
|
+
const featuresCloseMarker = '<!-- /wringer:features -->';
|
|
3
|
+
|
|
4
|
+
export type FeatureTableSpan =
|
|
5
|
+
| { readonly ok: true; readonly line: number; readonly table: string }
|
|
6
|
+
| { readonly ok: false; readonly line: number; readonly reason: string };
|
|
7
|
+
|
|
8
|
+
// The feature table that SKILL.md holds between its two markers, with the blank lines around it
|
|
9
|
+
// trimmed, and the line of the opening marker.
|
|
10
|
+
export function parseFeatureTableSpan(text: string): FeatureTableSpan {
|
|
11
|
+
const open = text.indexOf(featuresOpenMarker);
|
|
12
|
+
|
|
13
|
+
if (open === -1) {
|
|
14
|
+
return { ok: false, line: 1, reason: `SKILL.md has no \`${featuresOpenMarker}\` marker.` };
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
const line = text.slice(0, open).split('\n').length;
|
|
18
|
+
const bodyStart = open + featuresOpenMarker.length;
|
|
19
|
+
const close = text.indexOf(featuresCloseMarker, bodyStart);
|
|
20
|
+
|
|
21
|
+
if (close === -1) {
|
|
22
|
+
return { ok: false, line, reason: `SKILL.md has no \`${featuresCloseMarker}\` marker.` };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
return {
|
|
26
|
+
ok: true,
|
|
27
|
+
line,
|
|
28
|
+
table: text
|
|
29
|
+
.slice(bodyStart, close)
|
|
30
|
+
.replaceAll('\r\n', '\n')
|
|
31
|
+
.replaceAll(/^\n+|\n+$/gu, ''),
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const delimiterRowIndex = 1;
|
|
36
|
+
|
|
37
|
+
// The table without the column padding that a Markdown formatter adds: each row's cells trimmed,
|
|
38
|
+
// and each cell of the delimiter row cut to three dashes. An escaped pipe stays inside its cell.
|
|
39
|
+
export function toComparableTable(table: string): string {
|
|
40
|
+
return table
|
|
41
|
+
.split('\n')
|
|
42
|
+
.map((row, index) =>
|
|
43
|
+
row
|
|
44
|
+
.trim()
|
|
45
|
+
.split(/(?<!\\)\|/u)
|
|
46
|
+
.map((cell) => toComparableCell(cell, index === delimiterRowIndex))
|
|
47
|
+
.join('|'),
|
|
48
|
+
)
|
|
49
|
+
.join('\n');
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function toComparableCell(cell: string, isDelimiter: boolean): string {
|
|
53
|
+
const trimmed = cell.trim();
|
|
54
|
+
|
|
55
|
+
return isDelimiter ? trimmed.replace(/^:?-+:?$/u, '---') : trimmed;
|
|
56
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export interface GuideTopic {
|
|
2
|
+
readonly name: string;
|
|
3
|
+
readonly summary: string;
|
|
4
|
+
readonly text: string;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
// A topic's text opens with `# <title>`, and its next paragraph is the one-line summary that the
|
|
8
|
+
// topic list shows. A file with no summary gives an empty one, which the guide's own test refuses.
|
|
9
|
+
export function parseGuideTopic(name: string, text: string): GuideTopic {
|
|
10
|
+
const paragraphs = text.split(/\r?\n\r?\n/u);
|
|
11
|
+
const summary = (paragraphs[1] ?? '').replaceAll(/\s*\r?\n\s*/gu, ' ').trim();
|
|
12
|
+
|
|
13
|
+
return { name, summary, text };
|
|
14
|
+
}
|
|
@@ -4,22 +4,24 @@ import { parseShellWords } from './parse-shell-words.ts';
|
|
|
4
4
|
export type SkillMetadata =
|
|
5
5
|
| {
|
|
6
6
|
readonly ok: true;
|
|
7
|
-
readonly
|
|
7
|
+
readonly template: string | number;
|
|
8
8
|
readonly cliWords: readonly string[];
|
|
9
9
|
}
|
|
10
10
|
| { readonly ok: false; readonly reason: string };
|
|
11
11
|
|
|
12
|
+
const templateFieldSchema = z.union([z.string().min(1), z.number()]);
|
|
13
|
+
|
|
12
14
|
const frontmatterSchema = z.looseObject({
|
|
13
15
|
metadata: z.looseObject({
|
|
14
|
-
'wringer-template':
|
|
16
|
+
'wringer-template': templateFieldSchema,
|
|
15
17
|
'wringer-command': z.string().min(1),
|
|
16
18
|
}),
|
|
17
19
|
});
|
|
18
20
|
|
|
19
21
|
const frontmatterPattern = /^---\r?\n(?<yaml>[\s\S]*?)\r?\n---\r?\n/u;
|
|
20
22
|
|
|
21
|
-
// The wringer fields of a verify skill's YAML frontmatter: the template
|
|
22
|
-
//
|
|
23
|
+
// The wringer fields of a verify skill's YAML frontmatter: the template hash the skill was written
|
|
24
|
+
// from, and the words that call the repo's CLI, such as `bun verify`.
|
|
23
25
|
export function parseSkillMetadata(text: string): SkillMetadata {
|
|
24
26
|
const yaml = frontmatterPattern.exec(text)?.groups?.['yaml'];
|
|
25
27
|
|
|
@@ -33,7 +35,7 @@ export function parseSkillMetadata(text: string): SkillMetadata {
|
|
|
33
35
|
return {
|
|
34
36
|
ok: false,
|
|
35
37
|
reason:
|
|
36
|
-
'The frontmatter lacks `metadata.wringer-template` as a
|
|
38
|
+
'The frontmatter lacks `metadata.wringer-template` as a hash or `metadata.wringer-command` as text.',
|
|
37
39
|
};
|
|
38
40
|
}
|
|
39
41
|
|
|
@@ -43,7 +45,7 @@ export function parseSkillMetadata(text: string): SkillMetadata {
|
|
|
43
45
|
return { ok: false, reason: '`metadata.wringer-command` is not a command line.' };
|
|
44
46
|
}
|
|
45
47
|
|
|
46
|
-
return { ok: true,
|
|
48
|
+
return { ok: true, template: parsed.data.metadata['wringer-template'], cliWords };
|
|
47
49
|
}
|
|
48
50
|
|
|
49
51
|
// Bun's YAML parser throws on text that is not YAML; the schema then reports the field as missing.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { WringerError } from '@wringer/core';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
import type { GuideTopic } from './parse-guide-topic.ts';
|
|
4
|
+
|
|
5
|
+
const topicSummarySchema = z.strictObject({ name: z.string(), summary: z.string() });
|
|
6
|
+
|
|
7
|
+
const topicListSchema = z.strictObject({
|
|
8
|
+
version: z.string(),
|
|
9
|
+
topics: z.array(topicSummarySchema),
|
|
10
|
+
});
|
|
11
|
+
|
|
12
|
+
const topicTextSchema = z.strictObject({
|
|
13
|
+
version: z.string(),
|
|
14
|
+
topic: z.string(),
|
|
15
|
+
text: z.string(),
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
export const guideDataSchema = z.union([topicListSchema, topicTextSchema]);
|
|
19
|
+
|
|
20
|
+
export type GuideData = z.infer<typeof guideDataSchema>;
|
|
21
|
+
|
|
22
|
+
export interface Guide {
|
|
23
|
+
readonly version: string;
|
|
24
|
+
readonly topics: readonly GuideTopic[];
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
// With no topic, the list of topics; with one, its text. An unknown topic is a usage error that
|
|
28
|
+
// lists the topics, so an agent that guessed a name sees the right ones.
|
|
29
|
+
export function pickGuideData(guide: Guide, topic: string | undefined): GuideData | WringerError {
|
|
30
|
+
if (topic === undefined) {
|
|
31
|
+
return {
|
|
32
|
+
version: guide.version,
|
|
33
|
+
topics: guide.topics.map((entry) => ({ name: entry.name, summary: entry.summary })),
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const found = guide.topics.find((candidate) => candidate.name === topic);
|
|
38
|
+
|
|
39
|
+
if (found === undefined) {
|
|
40
|
+
return new WringerError('usage', {
|
|
41
|
+
message: `The guide has no topic named ${topic}.`,
|
|
42
|
+
hint: `The topics are ${guide.topics.map((candidate) => candidate.name).join(', ')}.`,
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
return { version: guide.version, topic: found.name, text: found.text };
|
|
47
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { readFile, readdir } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { parseGuideTopic } from './parse-guide-topic.ts';
|
|
5
|
+
import type { GuideTopic } from './parse-guide-topic.ts';
|
|
6
|
+
import type { Guide } from './pick-guide-data.ts';
|
|
7
|
+
|
|
8
|
+
const packageSchema = z.looseObject({ version: z.string().min(1) });
|
|
9
|
+
|
|
10
|
+
// The guide folder sits beside `src/` in the installed package, so the guide always matches the
|
|
11
|
+
// installed version, and reading it touches nothing outside that package.
|
|
12
|
+
export const guideFolder = join(import.meta.dir, '..', 'guide');
|
|
13
|
+
|
|
14
|
+
// One topic per Markdown file of the guide folder, and `template`, which names the folder of the
|
|
15
|
+
// template files to copy from.
|
|
16
|
+
export async function readGuide(folder: string = guideFolder): Promise<Guide> {
|
|
17
|
+
const [manifest, entries] = await Promise.all([
|
|
18
|
+
readFile(join(folder, '..', 'package.json'), 'utf8'),
|
|
19
|
+
readdir(folder, { withFileTypes: true }),
|
|
20
|
+
]);
|
|
21
|
+
|
|
22
|
+
const names = entries
|
|
23
|
+
.filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
|
|
24
|
+
.map((entry) => entry.name.replace(/\.md$/u, ''))
|
|
25
|
+
.toSorted();
|
|
26
|
+
|
|
27
|
+
const topics = await Promise.all(names.map((name) => readTopic(folder, name)));
|
|
28
|
+
|
|
29
|
+
return {
|
|
30
|
+
version: packageSchema.parse(JSON.parse(manifest)).version,
|
|
31
|
+
topics: [...topics, buildTemplateTopic(join(folder, 'template'))],
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
async function readTopic(folder: string, name: string): Promise<GuideTopic> {
|
|
36
|
+
const text = await readFile(join(folder, `${name}.md`), 'utf8');
|
|
37
|
+
|
|
38
|
+
return parseGuideTopic(name, text);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function buildTemplateTopic(templateFolder: string): GuideTopic {
|
|
42
|
+
const summary = 'Where the template files are, to copy from';
|
|
43
|
+
|
|
44
|
+
return {
|
|
45
|
+
name: 'template',
|
|
46
|
+
summary,
|
|
47
|
+
text: `# Template\n\n${summary}\n\nThe installed template folder is:\n\n${templateFolder}\n\nCopy from it as the \`overview\` and \`create\` topics say.\n`,
|
|
48
|
+
};
|
|
49
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { readFile, readdir } from 'node:fs/promises';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { guideFolder } from './read-guide.ts';
|
|
5
|
+
|
|
6
|
+
const templateFolder = join(guideFolder, 'template');
|
|
7
|
+
const hashLength = 12;
|
|
8
|
+
|
|
9
|
+
// A short hash of every template file except the tests, so an edit to any of them changes it. A
|
|
10
|
+
// repo's verify skill records it as `metadata.wringer-template`, and `lint` fails until the two
|
|
11
|
+
// match.
|
|
12
|
+
export async function readTemplateHash(folder: string = templateFolder): Promise<string> {
|
|
13
|
+
const entries = await readdir(folder, { recursive: true, withFileTypes: true });
|
|
14
|
+
|
|
15
|
+
const paths = entries
|
|
16
|
+
.filter((entry) => entry.isFile() && !entry.name.endsWith('.test.ts'))
|
|
17
|
+
.map((entry) => join(entry.parentPath, entry.name).slice(folder.length + 1))
|
|
18
|
+
.map((path) => path.replaceAll('\\', '/'))
|
|
19
|
+
.toSorted();
|
|
20
|
+
|
|
21
|
+
const hash = createHash('sha256');
|
|
22
|
+
|
|
23
|
+
for (const path of paths) {
|
|
24
|
+
const bytes = await readFile(join(folder, path));
|
|
25
|
+
|
|
26
|
+
hash.update(path).update('\0').update(maskRecordedHash(path, bytes)).update('\0');
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
return `sha256:${hash.digest('hex').slice(0, hashLength)}`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
// The template skill records the hash of the template in its own frontmatter, so the hash reads
|
|
33
|
+
// that one line with its value left out.
|
|
34
|
+
const recordedHashLine = /^(?<key>[ \t]*wringer-template:).*$/mu;
|
|
35
|
+
|
|
36
|
+
function maskRecordedHash(path: string, bytes: Buffer): Buffer {
|
|
37
|
+
if (!path.endsWith('SKILL.md')) {
|
|
38
|
+
return bytes;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
return Buffer.from(bytes.toString('utf8').replace(recordedHashLine, '$<key>'), 'utf8');
|
|
42
|
+
}
|
|
@@ -2,6 +2,7 @@ import type { Envelope } from '@wringer/core';
|
|
|
2
2
|
import { z } from 'zod';
|
|
3
3
|
|
|
4
4
|
const markdownDataSchema = z.looseObject({ markdown: z.string() });
|
|
5
|
+
const topicDataSchema = z.looseObject({ topic: z.string(), text: z.string() });
|
|
5
6
|
|
|
6
7
|
// A person reads the same envelope as an agent, as text: the error and its hint, or the data. A
|
|
7
8
|
// command whose data carries Markdown, such as `report`, prints only that Markdown.
|
|
@@ -18,6 +19,12 @@ export function renderHumanEnvelope(envelope: Envelope): string {
|
|
|
18
19
|
return `${markdown.data.markdown}\n`;
|
|
19
20
|
}
|
|
20
21
|
|
|
22
|
+
const topic = topicDataSchema.safeParse(envelope.data);
|
|
23
|
+
|
|
24
|
+
if (topic.success) {
|
|
25
|
+
return topic.data.text;
|
|
26
|
+
}
|
|
27
|
+
|
|
21
28
|
const truncated =
|
|
22
29
|
envelope.truncatedPath === undefined
|
|
23
30
|
? ''
|
|
@@ -1,14 +1,27 @@
|
|
|
1
|
+
import { buildFeatureFile, isGlobMatch, renderFeatureTable } from '@wringer/core';
|
|
1
2
|
import type { Wringer } from '@wringer/core';
|
|
2
3
|
import { z } from 'zod';
|
|
4
|
+
import { checkFeatureFile } from './check-feature-file.ts';
|
|
3
5
|
import { collectDeadGlobs } from './collect-dead-globs.ts';
|
|
4
6
|
import { collectJourneyCommands } from './collect-journey-commands.ts';
|
|
5
7
|
import type { JourneyCommand, MarkdownFile } from './collect-journey-commands.ts';
|
|
8
|
+
import { collectUnclaimedFiles } from './collect-unclaimed-files.ts';
|
|
9
|
+
import { parseFeatureTableSpan, toComparableTable } from './parse-feature-table-span.ts';
|
|
6
10
|
import { parseSkillMetadata } from './parse-skill-metadata.ts';
|
|
7
11
|
import type { SkillMetadata } from './parse-skill-metadata.ts';
|
|
8
12
|
import { resolveJourneyProblem } from './resolve-journey-problem.ts';
|
|
9
13
|
|
|
10
14
|
export const lintFailureSchema = z.strictObject({
|
|
11
|
-
|
|
15
|
+
// `where` names the feature, the glob group or the file that the check found at fault.
|
|
16
|
+
check: z.enum([
|
|
17
|
+
'paths',
|
|
18
|
+
'unclaimed',
|
|
19
|
+
'registry',
|
|
20
|
+
'journey',
|
|
21
|
+
'feature-file',
|
|
22
|
+
'feature-table',
|
|
23
|
+
'template',
|
|
24
|
+
]),
|
|
12
25
|
where: z.string(),
|
|
13
26
|
problem: z.string(),
|
|
14
27
|
});
|
|
@@ -22,9 +35,13 @@ export interface LintInput {
|
|
|
22
35
|
readonly files: readonly string[];
|
|
23
36
|
readonly skillPath: string;
|
|
24
37
|
|
|
38
|
+
// The registry's own file, relative to the repo root, or null when it is unknown or lies outside
|
|
39
|
+
// the repo.
|
|
40
|
+
readonly registryFile: string | null;
|
|
41
|
+
|
|
25
42
|
// The Markdown files of the verify skill's folder, its SKILL.md included when it exists.
|
|
26
43
|
readonly skillFiles: readonly MarkdownFile[];
|
|
27
|
-
readonly
|
|
44
|
+
readonly templateHash: string;
|
|
28
45
|
}
|
|
29
46
|
|
|
30
47
|
export interface LintResult {
|
|
@@ -46,20 +63,34 @@ export async function resolveLintFailures(input: LintInput): Promise<LintResult>
|
|
|
46
63
|
journeys.map((journey) => resolveJourneyFailure(input.wringer, journey)),
|
|
47
64
|
);
|
|
48
65
|
|
|
49
|
-
const pathFailures = collectDeadGlobs(input.wringer
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
66
|
+
const pathFailures = collectDeadGlobs(input.wringer, input.files).map((dead): LintFailure => ({
|
|
67
|
+
check: 'paths',
|
|
68
|
+
where: dead.where,
|
|
69
|
+
problem: `The glob \`${dead.glob}\` matches no file.`,
|
|
70
|
+
}));
|
|
71
|
+
|
|
72
|
+
const unclaimedFailures = collectUnclaimedFiles(input.wringer, input.files).map(
|
|
73
|
+
(file): LintFailure => ({
|
|
74
|
+
check: 'unclaimed',
|
|
75
|
+
where: file,
|
|
76
|
+
problem:
|
|
77
|
+
'No feature `paths`, shared or ignore glob matches the file. Add it to a feature, `.shared()` or `.ignore()`.',
|
|
54
78
|
}),
|
|
55
79
|
);
|
|
56
80
|
|
|
81
|
+
const cliWords = metadata?.ok === true ? metadata.cliWords : null;
|
|
82
|
+
|
|
57
83
|
return {
|
|
58
84
|
commands: journeys.length,
|
|
59
85
|
failures: [
|
|
60
86
|
...pathFailures,
|
|
87
|
+
...unclaimedFailures,
|
|
88
|
+
...collectRegistryFailures(input.wringer, input.registryFile),
|
|
89
|
+
...collectUploadFailures(input.wringer),
|
|
61
90
|
...journeyFailures.filter((failure) => failure !== null),
|
|
62
|
-
...
|
|
91
|
+
...collectFeatureFileFailures(input, cliWords),
|
|
92
|
+
...collectFeatureTableFailures(input, skill?.text ?? null, cliWords),
|
|
93
|
+
...collectTemplateFailures(metadata, input.skillPath, input.templateHash),
|
|
63
94
|
],
|
|
64
95
|
};
|
|
65
96
|
}
|
|
@@ -84,10 +115,145 @@ async function resolveJourneyFailure(
|
|
|
84
115
|
};
|
|
85
116
|
}
|
|
86
117
|
|
|
118
|
+
// The registry file must sit under a shared glob or a feature's `paths`, so a change to it makes
|
|
119
|
+
// the verdicts it can affect stale. An ignore glob does not count as cover.
|
|
120
|
+
function collectRegistryFailures(
|
|
121
|
+
wringer: Wringer,
|
|
122
|
+
registryFile: string | null,
|
|
123
|
+
): readonly LintFailure[] {
|
|
124
|
+
if (registryFile === null) {
|
|
125
|
+
return [];
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const covered =
|
|
129
|
+
isGlobMatch(registryFile, wringer.shared) ||
|
|
130
|
+
wringer.features.some((feature) => isGlobMatch(registryFile, feature.paths));
|
|
131
|
+
|
|
132
|
+
if (covered) {
|
|
133
|
+
return [];
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
return [
|
|
137
|
+
{
|
|
138
|
+
check: 'registry',
|
|
139
|
+
where: registryFile,
|
|
140
|
+
problem:
|
|
141
|
+
'No shared glob and no feature `paths` glob matches the registry file, so a change to it leaves every verdict standing. Add the file to `.shared()`.',
|
|
142
|
+
},
|
|
143
|
+
];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// A target that uploads its evidence needs the hook that does it, or `publish` fails.
|
|
147
|
+
function collectUploadFailures(wringer: Wringer): readonly LintFailure[] {
|
|
148
|
+
if (wringer.hooks.upload !== undefined) {
|
|
149
|
+
return [];
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
return [...wringer.targets]
|
|
153
|
+
.filter(([, target]) => target.evidence === 'upload')
|
|
154
|
+
.map(([name]): LintFailure => ({
|
|
155
|
+
check: 'registry',
|
|
156
|
+
where: `target ${name}`,
|
|
157
|
+
problem:
|
|
158
|
+
"The target sets `evidence: 'upload'` and the registry has no `upload` hook. Add `.hook('upload', createHostUploader(…))`, or set `evidence: 'local'`.",
|
|
159
|
+
}));
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
const featureFilePattern = /^references\/feature-(?<name>.+)\.md$/u;
|
|
163
|
+
|
|
164
|
+
// Each feature needs `references/feature-<name>.md` in the skill folder, each such file needs a
|
|
165
|
+
// feature, and each file needs the Journey and End state sections.
|
|
166
|
+
function collectFeatureFileFailures(
|
|
167
|
+
input: LintInput,
|
|
168
|
+
cliWords: readonly string[] | null,
|
|
169
|
+
): readonly LintFailure[] {
|
|
170
|
+
const folder = input.skillPath.slice(0, input.skillPath.lastIndexOf('/') + 1);
|
|
171
|
+
|
|
172
|
+
const names = new Set(input.wringer.features.map((feature) => feature.name));
|
|
173
|
+
|
|
174
|
+
const missing = input.wringer.features.flatMap((feature): LintFailure[] => {
|
|
175
|
+
const file = buildFeatureFile(feature.name);
|
|
176
|
+
|
|
177
|
+
return input.skillFiles.some((candidate) => candidate.path === `${folder}${file}`)
|
|
178
|
+
? []
|
|
179
|
+
: [
|
|
180
|
+
{
|
|
181
|
+
check: 'feature-file',
|
|
182
|
+
where: `feature ${feature.name}`,
|
|
183
|
+
problem: `The skill folder has no \`${file}\`. Write it with a Journey and an End state.`,
|
|
184
|
+
},
|
|
185
|
+
];
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
const present = input.skillFiles.flatMap((file) => {
|
|
189
|
+
const name = featureFilePattern.exec(file.path.slice(folder.length))?.groups?.['name'];
|
|
190
|
+
|
|
191
|
+
return file.path.startsWith(folder) && name !== undefined ? [{ file, name }] : [];
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
const orphaned = present
|
|
195
|
+
.filter((entry) => !names.has(entry.name))
|
|
196
|
+
.map((entry): LintFailure => ({
|
|
197
|
+
check: 'feature-file',
|
|
198
|
+
where: `${entry.file.path}:1`,
|
|
199
|
+
problem: `The registry has no feature named ${entry.name}. Remove the file, or register the feature.`,
|
|
200
|
+
}));
|
|
201
|
+
|
|
202
|
+
const misshapen = present
|
|
203
|
+
.filter((entry) => names.has(entry.name))
|
|
204
|
+
.flatMap((entry) =>
|
|
205
|
+
checkFeatureFile(entry.file.text, entry.name, cliWords).map((found): LintFailure => ({
|
|
206
|
+
check: 'feature-file',
|
|
207
|
+
where: `${entry.file.path}:${found.line}`,
|
|
208
|
+
problem: found.problem,
|
|
209
|
+
})),
|
|
210
|
+
);
|
|
211
|
+
|
|
212
|
+
return [...missing, ...orphaned, ...misshapen];
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function collectFeatureTableFailures(
|
|
216
|
+
input: LintInput,
|
|
217
|
+
skillText: string | null,
|
|
218
|
+
cliWords: readonly string[] | null,
|
|
219
|
+
): readonly LintFailure[] {
|
|
220
|
+
if (skillText === null) {
|
|
221
|
+
return [];
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const span = parseFeatureTableSpan(skillText);
|
|
225
|
+
const command = `${[...(cliWords ?? [])].join(' ')} features --markdown`.trim();
|
|
226
|
+
const hint = `Replace the span with the output of \`${command}\`.`;
|
|
227
|
+
|
|
228
|
+
if (!span.ok) {
|
|
229
|
+
return [
|
|
230
|
+
{
|
|
231
|
+
check: 'feature-table',
|
|
232
|
+
where: `${input.skillPath}:${span.line}`,
|
|
233
|
+
problem: `${span.reason} ${hint}`,
|
|
234
|
+
},
|
|
235
|
+
];
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
if (
|
|
239
|
+
toComparableTable(span.table) === toComparableTable(renderFeatureTable(input.wringer.features))
|
|
240
|
+
) {
|
|
241
|
+
return [];
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
return [
|
|
245
|
+
{
|
|
246
|
+
check: 'feature-table',
|
|
247
|
+
where: `${input.skillPath}:${span.line}`,
|
|
248
|
+
problem: `The feature table differs from the registry's features. ${hint}`,
|
|
249
|
+
},
|
|
250
|
+
];
|
|
251
|
+
}
|
|
252
|
+
|
|
87
253
|
function collectTemplateFailures(
|
|
88
254
|
metadata: SkillMetadata | null,
|
|
89
255
|
skillPath: string,
|
|
90
|
-
|
|
256
|
+
templateHash: string,
|
|
91
257
|
): readonly LintFailure[] {
|
|
92
258
|
if (metadata === null) {
|
|
93
259
|
return [{ check: 'template', where: skillPath, problem: 'The verify skill is missing.' }];
|
|
@@ -97,15 +263,20 @@ function collectTemplateFailures(
|
|
|
97
263
|
return [{ check: 'template', where: skillPath, problem: metadata.reason }];
|
|
98
264
|
}
|
|
99
265
|
|
|
100
|
-
if (metadata.
|
|
266
|
+
if (metadata.template === templateHash) {
|
|
101
267
|
return [];
|
|
102
268
|
}
|
|
103
269
|
|
|
270
|
+
const recorded =
|
|
271
|
+
typeof metadata.template === 'number'
|
|
272
|
+
? `a template version number, ${metadata.template}`
|
|
273
|
+
: `template ${metadata.template}`;
|
|
274
|
+
|
|
104
275
|
return [
|
|
105
276
|
{
|
|
106
277
|
check: 'template',
|
|
107
278
|
where: skillPath,
|
|
108
|
-
problem: `The skill
|
|
279
|
+
problem: `The skill records ${recorded}, and the installed @wringer/gunshi ships template ${templateHash}. Run \`bun verify guide template\` for the template folder, bring the skill up to date with it, and set \`metadata.wringer-template\` to \`${templateHash}\`.`,
|
|
109
280
|
},
|
|
110
281
|
];
|
|
111
282
|
}
|
package/src/run-cli.ts
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
import { dispatch, supervisorCommandName } from '@wringer/core';
|
|
2
|
-
import type {
|
|
2
|
+
import type {
|
|
3
|
+
PullRequestHost,
|
|
4
|
+
RepoHost,
|
|
5
|
+
StatePort,
|
|
6
|
+
SupervisorPort,
|
|
7
|
+
Wringer,
|
|
8
|
+
WringerError,
|
|
9
|
+
} from '@wringer/core';
|
|
3
10
|
import { parseArgs } from 'gunshi';
|
|
4
11
|
import type { Invocation } from './build-gunshi-commands.ts';
|
|
5
12
|
import { pickCLIOutcome } from './pick-cli-outcome.ts';
|
|
@@ -9,10 +16,12 @@ import type { OutputMode } from './pick-output-mode.ts';
|
|
|
9
16
|
import { renderEnvelope } from './render-envelope.ts';
|
|
10
17
|
import { renderHumanEvent } from './render-human-event.ts';
|
|
11
18
|
import { resolveInvocation } from './resolve-invocation.ts';
|
|
19
|
+
import { scrubParsedInvocation } from './scrub-parsed-invocation.ts';
|
|
12
20
|
|
|
13
21
|
interface RepoPorts {
|
|
14
22
|
readonly state: StatePort;
|
|
15
23
|
readonly repoHost: RepoHost;
|
|
24
|
+
readonly pullRequests: PullRequestHost;
|
|
16
25
|
readonly supervisor: SupervisorPort;
|
|
17
26
|
}
|
|
18
27
|
|
|
@@ -21,6 +30,9 @@ export interface CLIPorts {
|
|
|
21
30
|
readonly cwd: string;
|
|
22
31
|
readonly isTTY: boolean;
|
|
23
32
|
readonly isAgent: boolean;
|
|
33
|
+
|
|
34
|
+
// The process environment, whose secret-looking values every command scrubs from what it writes.
|
|
35
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
24
36
|
readonly writeStdout: (text: string) => void;
|
|
25
37
|
readonly readRepoRoot: (cwd: string) => Promise<string | WringerError>;
|
|
26
38
|
readonly openRepo: (root: string) => RepoPorts;
|
|
@@ -41,8 +53,9 @@ export async function runCLI(wringer: Wringer, ports: CLIPorts): Promise<number>
|
|
|
41
53
|
const tokens = parseArgs([...ports.argv]);
|
|
42
54
|
const mode = pickOutputMode({ tokens, isTTY: ports.isTTY, isAgent: ports.isAgent });
|
|
43
55
|
|
|
44
|
-
const
|
|
56
|
+
const resolved = await resolveInvocation(wringer, ports.argv);
|
|
45
57
|
|
|
58
|
+
const parsed = scrubParsedInvocation(resolved, wringer, ports.env);
|
|
46
59
|
const outcome = pickCLIOutcome(parsed, mode);
|
|
47
60
|
|
|
48
61
|
if (outcome.kind === 'dispatch') {
|
|
@@ -76,7 +89,9 @@ async function dispatchInvocation(
|
|
|
76
89
|
root: plan.root,
|
|
77
90
|
state: repo.state,
|
|
78
91
|
repoHost: repo.repoHost,
|
|
92
|
+
pullRequests: repo.pullRequests,
|
|
79
93
|
supervisor: repo.supervisor,
|
|
94
|
+
env: ports.env,
|
|
80
95
|
target: invocation.globals.target,
|
|
81
96
|
feature: invocation.globals.feature,
|
|
82
97
|
timeoutMs: invocation.globals.timeoutMs,
|
package/src/run-verify.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import {
|
|
2
|
+
createNodePullRequestHost,
|
|
2
3
|
createNodeRepoHost,
|
|
3
4
|
createRepoState,
|
|
4
5
|
makeProcessSupervisorPort,
|
|
@@ -6,13 +7,18 @@ import {
|
|
|
6
7
|
} from '@wringer/core';
|
|
7
8
|
import type { Wringer } from '@wringer/core';
|
|
8
9
|
import { getAgentProfile } from 'gunshi/agent';
|
|
9
|
-
import {
|
|
10
|
+
import { buildCLIWringer } from './build-cli-wringer.ts';
|
|
10
11
|
import { readRepoRoot } from './read-repo-root.ts';
|
|
11
12
|
import { runCLI } from './run-cli.ts';
|
|
13
|
+
import type { CLIPorts } from './run-cli.ts';
|
|
12
14
|
|
|
13
15
|
export interface VerifyOptions {
|
|
14
16
|
// The folder of the repo's verify skill, relative to the repo root, which `lint` checks.
|
|
15
17
|
readonly skill?: string | undefined;
|
|
18
|
+
|
|
19
|
+
// The registry's own file, relative to the repo root, which `lint` checks for cover by a shared
|
|
20
|
+
// glob or a feature's `paths`. It defaults to the script that runs the CLI.
|
|
21
|
+
readonly registry?: string | undefined;
|
|
16
22
|
}
|
|
17
23
|
|
|
18
24
|
const defaultSkillFolder = '.claude/skills/verify';
|
|
@@ -22,25 +28,42 @@ const defaultSkillFolder = '.claude/skills/verify';
|
|
|
22
28
|
// arguments.
|
|
23
29
|
export async function runVerify(wringer: Wringer, options: VerifyOptions = {}): Promise<void> {
|
|
24
30
|
const [, script] = process.argv;
|
|
31
|
+
|
|
32
|
+
await runWringer(
|
|
33
|
+
buildCLIWringer(
|
|
34
|
+
wringer,
|
|
35
|
+
options.skill ?? defaultSkillFolder,
|
|
36
|
+
options.registry ?? script ?? null,
|
|
37
|
+
),
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// Runs a registry as the process's CLI, with the process's arguments, streams and exit code.
|
|
42
|
+
export async function runWringer(
|
|
43
|
+
wringer: Wringer,
|
|
44
|
+
repoPorts?: Pick<CLIPorts, 'readRepoRoot' | 'openRepo'>,
|
|
45
|
+
): Promise<void> {
|
|
46
|
+
const [, script] = process.argv;
|
|
25
47
|
const selfCommand = script === undefined ? [process.execPath] : [process.execPath, script];
|
|
26
48
|
|
|
27
|
-
process.exitCode = await runCLI(
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
49
|
+
process.exitCode = await runCLI(wringer, {
|
|
50
|
+
argv: process.argv.slice(2),
|
|
51
|
+
cwd: process.cwd(),
|
|
52
|
+
isTTY: process.stdout.isTTY,
|
|
53
|
+
isAgent: getAgentProfile().isAgent,
|
|
54
|
+
env: process.env,
|
|
55
|
+
writeStdout: (text) => {
|
|
56
|
+
process.stdout.write(text);
|
|
57
|
+
},
|
|
58
|
+
...(repoPorts ?? {
|
|
37
59
|
readRepoRoot,
|
|
38
|
-
openRepo: (root) => ({
|
|
60
|
+
openRepo: (root: string) => ({
|
|
39
61
|
state: createRepoState(root, wringer.stateDir),
|
|
40
62
|
repoHost: createNodeRepoHost(),
|
|
63
|
+
pullRequests: createNodePullRequestHost(root),
|
|
41
64
|
supervisor: makeProcessSupervisorPort({ selfCommand, root, stateDir: wringer.stateDir }),
|
|
42
65
|
}),
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
);
|
|
66
|
+
}),
|
|
67
|
+
runSupervisor: runSupervisorProcess,
|
|
68
|
+
});
|
|
46
69
|
}
|