e2e-qa-pilot 0.0.0-stage → 0.4.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/src/kit.mjs ADDED
@@ -0,0 +1,89 @@
1
+ import { fileURLToPath } from 'node:url';
2
+ import path from 'node:path';
3
+ import fs from 'node:fs';
4
+
5
+ // Shared facts for init and the MCP server.
6
+ // CATALOG must match the command folders under processes/create-e2e/commands/.
7
+ // Those Markdown files are the spec. The descriptions here are only the short MCP blurbs.
8
+ // EDITORS is the map from an editor name to its skill folder, MCP file, and label.
9
+
10
+ export const kitRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
11
+ export const MARKER = 'e2e-qa-pilot:managed';
12
+ export const MARKER_LINE = `<!-- ${MARKER} -->`;
13
+ export const SERVER_NAME = 'e2e-qa-pilot';
14
+
15
+ // One input object for every Create e2e tool. required is empty because the
16
+ // caller sends exactly one of the two fields. The handler rejects both and neither.
17
+ export const CASE_INPUT_SCHEMA = {
18
+ type: 'object',
19
+ properties: {
20
+ case_id: {
21
+ type: 'string',
22
+ description:
23
+ 'Id of an existing case in the configured case tool, such as a Qase id. Do not put test case text here. Mutually exclusive with case_text.',
24
+ },
25
+ case_text: {
26
+ type: 'string',
27
+ description:
28
+ 'Complete test case text, including preconditions, steps, and expected results. Use a Title line when the title is known. Mutually exclusive with case_id. No case tool is required.',
29
+ },
30
+ },
31
+ required: [],
32
+ additionalProperties: false,
33
+ };
34
+
35
+ export const CATALOG = [
36
+ {
37
+ command: 'review-case',
38
+ tool: 'review_case',
39
+ description:
40
+ 'Resolve one case, either by case_id from the configured case tool or by case_text pasted in full. Check that the steps are specific enough to assert, ask one question per hole, update that same case only when it came from a case id, then route to add_from_steps or add_from_design. Returns the instructions to follow. Does not write a spec.',
41
+ },
42
+ {
43
+ command: 'add-from-steps',
44
+ tool: 'add_from_steps',
45
+ description:
46
+ 'Write the Playwright spec and open a pull request from a reviewed case supplied as case_id or case_text. Use this when the case has no Figma link, or figma is off. Steps and expected results are the oracle. Returns the instructions to follow.',
47
+ },
48
+ {
49
+ command: 'add-from-design',
50
+ tool: 'add_from_design',
51
+ description:
52
+ 'Write the Playwright spec for a reviewed case supplied as case_id or case_text that has a figma.com URL and figma: on. Compares each milestone with its frame. A narrow minor text difference is documented as e2e:minor-text-diff. Other differences follow pr_mode and can be a draft e2e:mismatch. Returns the instructions to follow.',
53
+ },
54
+ ];
55
+
56
+ export const COMMANDS = CATALOG.map((entry) => entry.command);
57
+
58
+ export const EDITORS = {
59
+ cursor: {
60
+ skillsDir: '.cursor',
61
+ mcpFile: path.join('.cursor', 'mcp.json'),
62
+ label: 'Cursor',
63
+ },
64
+ claude: {
65
+ skillsDir: '.claude',
66
+ mcpFile: '.mcp.json',
67
+ label: 'Claude Code',
68
+ },
69
+ };
70
+
71
+ export const commandsDir = path.join(kitRoot, 'processes', 'create-e2e', 'commands');
72
+
73
+ export function readPackageVersion() {
74
+ const pkg = JSON.parse(fs.readFileSync(path.join(kitRoot, 'package.json'), 'utf8'));
75
+ return pkg.version;
76
+ }
77
+
78
+ export function listFiles(dir) {
79
+ const found = [];
80
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
81
+ const full = path.join(dir, entry.name);
82
+ if (entry.isDirectory()) {
83
+ found.push(...listFiles(full));
84
+ } else if (entry.isFile()) {
85
+ found.push(full);
86
+ }
87
+ }
88
+ return found;
89
+ }
package/src/mcp.mjs ADDED
@@ -0,0 +1,227 @@
1
+ import path from 'node:path';
2
+ import fs from 'node:fs';
3
+ import readline from 'node:readline';
4
+ import { commandsDir, CATALOG, CASE_INPUT_SCHEMA, SERVER_NAME, readPackageVersion } from './kit.mjs';
5
+
6
+ // A small stdio MCP server with no dependencies, so every line it runs can be read.
7
+ // Tool names, descriptions, and the input schema come from kit.mjs.
8
+ // It never contacts a case tool, never calls a network, and never reads a secret.
9
+ // Case text in a tool call is the text the client sent.
10
+ // It hands the assistant the command file, the shared rules, and the project settings.
11
+ // Stdout is JSON-RPC only. Faults go to stderr.
12
+
13
+ const TOOLS = Object.fromEntries(
14
+ CATALOG.map((entry) => [
15
+ entry.tool,
16
+ { command: entry.command, description: entry.description },
17
+ ]),
18
+ );
19
+
20
+ const INPUT_KEYS = ['case_id', 'case_text'];
21
+
22
+ function read(file) {
23
+ return fs.readFileSync(file, 'utf8');
24
+ }
25
+
26
+ function isRecord(value) {
27
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
28
+ }
29
+
30
+ function presentText(value) {
31
+ return typeof value === 'string' ? value.trim() : '';
32
+ }
33
+
34
+ function resolveCaseInput(args) {
35
+ if (args === undefined || args === null) {
36
+ return { error: 'Provide case_id or case_text. Ask the human for one of them.' };
37
+ }
38
+ if (!isRecord(args)) {
39
+ return { error: 'Tool arguments must be an object.' };
40
+ }
41
+ const unknown = Object.keys(args).filter((key) => !INPUT_KEYS.includes(key));
42
+ if (unknown.length > 0) {
43
+ return { error: `Unknown input: ${unknown.join(', ')}.` };
44
+ }
45
+ for (const key of INPUT_KEYS) {
46
+ if (args[key] !== undefined && typeof args[key] !== 'string') {
47
+ return { error: `${key} must be a string.` };
48
+ }
49
+ }
50
+ const caseId = presentText(args.case_id);
51
+ const caseText = presentText(args.case_text);
52
+ if (caseId && caseText) {
53
+ return { error: 'Provide either case_id or case_text, not both.' };
54
+ }
55
+ if (!caseId && !caseText) {
56
+ return { error: 'Provide case_id or case_text. Ask the human for one of them.' };
57
+ }
58
+ if (caseId) return { mode: 'case_id', caseId };
59
+ return { mode: 'case_text', caseText };
60
+ }
61
+
62
+ function sourceBlock(source) {
63
+ if (source.mode === 'case_id') {
64
+ return [
65
+ 'Input mode: case_id',
66
+ '',
67
+ `Case id: ${source.caseId}`,
68
+ '',
69
+ 'Fetch this id with fetch_case from settings.',
70
+ 'If the case tool errors or the case does not exist, stop and report that.',
71
+ 'Do not invent the case. Do not treat this id as test case text.',
72
+ ].join('\n');
73
+ }
74
+ return [
75
+ 'Input mode: case_text',
76
+ '',
77
+ 'Case text:',
78
+ '',
79
+ source.caseText,
80
+ '',
81
+ 'This text is the case. Do not call fetch_case or update_case. A case tool is not required.',
82
+ ].join('\n');
83
+ }
84
+
85
+ export function buildToolText(toolName, source, projectDir) {
86
+ const tool = TOOLS[toolName];
87
+ const skill = read(path.join(commandsDir, tool.command, 'SKILL.md'));
88
+ const ready = read(path.join(commandsDir, 'shared', 'ready-rules.md'));
89
+ const evidence = read(path.join(commandsDir, 'shared', 'pr-evidence.md'));
90
+
91
+ const settingsPath = path.join(projectDir, '.e2e-qa-pilot', 'settings.md');
92
+ const settings = fs.existsSync(settingsPath)
93
+ ? read(settingsPath)
94
+ : `(missing: ${settingsPath}. Run \`npx e2e-qa-pilot init\` in the project.)`;
95
+
96
+ return [
97
+ `# ${SERVER_NAME}: ${toolName}`,
98
+ '',
99
+ sourceBlock(source),
100
+ '',
101
+ 'You do the work yourself with the tools you already have (your case tool, Playwright, GitHub).',
102
+ 'This server fetched nothing. Ask the human when a step is vague, read every screenshot yourself,',
103
+ 'and never paste a secret into the chat.',
104
+ '',
105
+ '## Settings (.e2e-qa-pilot/settings.md)',
106
+ '',
107
+ settings,
108
+ '',
109
+ '## Instructions',
110
+ '',
111
+ skill,
112
+ '',
113
+ '## Shared: ready-rules.md',
114
+ '',
115
+ ready,
116
+ '',
117
+ '## Shared: pr-evidence.md',
118
+ '',
119
+ evidence,
120
+ ].join('\n');
121
+ }
122
+
123
+ function reply(id, result) {
124
+ process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
125
+ }
126
+
127
+ function fail(id, code, message) {
128
+ process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
129
+ }
130
+
131
+ export function handleMessage(message, projectDir) {
132
+ if (!isRecord(message)) {
133
+ return { error: { code: -32700, message: 'Parse error' } };
134
+ }
135
+ const { id, method, params } = message;
136
+ const isNotification = id === undefined || id === null;
137
+
138
+ switch (method) {
139
+ case 'initialize':
140
+ return {
141
+ result: {
142
+ protocolVersion: params?.protocolVersion ?? '2025-03-26',
143
+ capabilities: { tools: {} },
144
+ serverInfo: { name: SERVER_NAME, version: readPackageVersion() },
145
+ },
146
+ };
147
+ case 'ping':
148
+ return { result: {} };
149
+ case 'tools/list':
150
+ return {
151
+ result: {
152
+ tools: Object.entries(TOOLS).map(([name, tool]) => ({
153
+ name,
154
+ description: tool.description,
155
+ inputSchema: CASE_INPUT_SCHEMA,
156
+ })),
157
+ },
158
+ };
159
+ case 'tools/call': {
160
+ const name = params?.name;
161
+ if (!TOOLS[name]) {
162
+ return { error: { code: -32602, message: `Unknown tool: ${name}` } };
163
+ }
164
+ const source = resolveCaseInput(params?.arguments);
165
+ if (source.error) {
166
+ return {
167
+ result: {
168
+ isError: true,
169
+ content: [{ type: 'text', text: source.error }],
170
+ },
171
+ };
172
+ }
173
+ return {
174
+ result: {
175
+ content: [{ type: 'text', text: buildToolText(name, source, projectDir) }],
176
+ },
177
+ };
178
+ }
179
+ default:
180
+ if (isNotification) return null;
181
+ return { error: { code: -32601, message: `Method not found: ${method}` } };
182
+ }
183
+ }
184
+
185
+ function respond(message, outcome) {
186
+ if (!outcome) return;
187
+ const id = isRecord(message) ? message.id : undefined;
188
+ if (id === undefined || id === null) {
189
+ if (outcome.error) {
190
+ process.stderr.write(`${outcome.error.message}\n`);
191
+ fail(null, outcome.error.code, outcome.error.message);
192
+ }
193
+ return;
194
+ }
195
+ if (outcome.error) fail(id, outcome.error.code, outcome.error.message);
196
+ else reply(id, outcome.result);
197
+ }
198
+
199
+ export function runMcp({ projectDir = process.cwd() } = {}) {
200
+ const rl = readline.createInterface({ input: process.stdin });
201
+ rl.on('line', (line) => {
202
+ if (!line.trim()) return;
203
+ let message;
204
+ try {
205
+ message = JSON.parse(line);
206
+ } catch {
207
+ process.stderr.write('Parse error\n');
208
+ fail(null, -32700, 'Parse error');
209
+ return;
210
+ }
211
+ let outcome;
212
+ try {
213
+ outcome = handleMessage(message, projectDir);
214
+ } catch (error) {
215
+ const text = error instanceof Error ? error.message : String(error);
216
+ const id = isRecord(message) ? message.id : undefined;
217
+ if (id !== undefined && id !== null) {
218
+ fail(id, -32603, text);
219
+ } else {
220
+ process.stderr.write(`${text}\n`);
221
+ fail(null, -32603, text);
222
+ }
223
+ return;
224
+ }
225
+ respond(message, outcome);
226
+ });
227
+ }
@@ -0,0 +1,57 @@
1
+ # Settings
2
+
3
+ ## Context
4
+
5
+ ## Requirements
6
+
7
+ ## Goal
8
+
9
+ branch_pattern: e2e/{title_slug}
10
+ pr_mode: create_pr_for_review
11
+ pr_label_ready: e2e:ready
12
+ pr_label_minor_text_diff: e2e:minor-text-diff
13
+ pr_label_mismatch: e2e:mismatch
14
+
15
+ <!--
16
+ case_tool, fetch_case, and update_case are only for a case id.
17
+ Pasted case text does not use them. Leave them empty if you have no case tool.
18
+
19
+ pr_mode is create_pr_for_review by default. The other value is ask_before_pr.
20
+ A missing pr_mode uses create_pr_for_review. Do not ask.
21
+ A missing label uses the default below. Do not ask.
22
+
23
+ branch_pattern names the branch. {title_slug} is the case title in kebab-case.
24
+ {case_id} is filled in only for a case id. A missing branch_pattern uses
25
+ e2e/{title_slug}, or e2e/{case_id}-{title_slug} for a case id. A value without a
26
+ placeholder is a literal name and puts every case on that one branch.
27
+
28
+ Keys, case tool with Figma on:
29
+
30
+ case_tool:
31
+ fetch_case:
32
+ update_case:
33
+ figma: on
34
+ read_figma:
35
+ branch_pattern: e2e/{title_slug}
36
+ test_command:
37
+ png_dir:
38
+ pr_mode: create_pr_for_review
39
+ pr_label_ready: e2e:ready
40
+ pr_label_minor_text_diff: e2e:minor-text-diff
41
+ pr_label_mismatch: e2e:mismatch
42
+
43
+ Keys, case tool with Figma left off:
44
+
45
+ case_tool:
46
+ fetch_case:
47
+ update_case:
48
+ figma: off
49
+ read_figma:
50
+ branch_pattern: e2e/{title_slug}
51
+ test_command:
52
+ png_dir:
53
+ pr_mode: create_pr_for_review
54
+ pr_label_ready: e2e:ready
55
+ pr_label_minor_text_diff: e2e:minor-text-diff
56
+ pr_label_mismatch: e2e:mismatch
57
+ -->