e2e-qa-pilot 0.4.0 → 0.4.5

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 CHANGED
@@ -32,6 +32,14 @@ export const CASE_INPUT_SCHEMA = {
32
32
  additionalProperties: false,
33
33
  };
34
34
 
35
+ // setup_project takes no case. It only helps the human fill .e2e-qa-pilot/project.md.
36
+ export const NO_INPUT_SCHEMA = {
37
+ type: 'object',
38
+ properties: {},
39
+ required: [],
40
+ additionalProperties: false,
41
+ };
42
+
35
43
  export const CATALOG = [
36
44
  {
37
45
  command: 'review-case',
@@ -51,23 +59,37 @@ export const CATALOG = [
51
59
  description:
52
60
  '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
61
  },
62
+ {
63
+ command: 'setup-project',
64
+ tool: 'setup_project',
65
+ input: 'none',
66
+ description:
67
+ 'Fill in .e2e-qa-pilot/project.md for this repository: ticket id, branch and commit format, case tool, Figma, feature flags, read-only context repositories, and test layout. Inspects the repo first and asks one batch of questions only for what it cannot detect. Takes no case. Returns the instructions to follow.',
68
+ },
54
69
  ];
55
70
 
56
71
  export const COMMANDS = CATALOG.map((entry) => entry.command);
57
72
 
73
+ // Each editor gets the same skills and the same always-on text.
74
+ // alwaysOn is where that text goes: a Cursor rule file, or a managed block in CLAUDE.md.
58
75
  export const EDITORS = {
59
76
  cursor: {
60
77
  skillsDir: '.cursor',
61
78
  mcpFile: path.join('.cursor', 'mcp.json'),
62
79
  label: 'Cursor',
80
+ alwaysOn: { kind: 'file', file: path.join('.cursor', 'rules', 'e2e-qa-pilot.mdc') },
63
81
  },
64
82
  claude: {
65
83
  skillsDir: '.claude',
66
84
  mcpFile: '.mcp.json',
67
85
  label: 'Claude Code',
86
+ alwaysOn: { kind: 'block', file: 'CLAUDE.md' },
68
87
  },
69
88
  };
70
89
 
90
+ export const BLOCK_START = '<!-- e2e-qa-pilot:begin -->';
91
+ export const BLOCK_END = '<!-- e2e-qa-pilot:end -->';
92
+
71
93
  export const commandsDir = path.join(kitRoot, 'processes', 'create-e2e', 'commands');
72
94
 
73
95
  export function readPackageVersion() {
@@ -0,0 +1,70 @@
1
+ import path from 'node:path';
2
+ import fs from 'node:fs';
3
+ import crypto from 'node:crypto';
4
+
5
+ // .e2e-qa-pilot/manifest.json records what init installed, so upgrade can tell a file
6
+ // the package wrote from a file the person edited.
7
+ //
8
+ // {
9
+ // "schema": 1, shape of this file; changes only with a migration
10
+ // "package_version": "0.5.0", the package that last wrote these files
11
+ // "integrations": ["cursor"], editors that were set up
12
+ // "files": { "<path>": "<sha256 of the text the package wrote>" },
13
+ // "templates": { "project_headings": [...], "settings_keys": [...] }
14
+ // what the templates held at install, so upgrade
15
+ // can name sections and keys added since
16
+ // }
17
+ //
18
+ // It lists only files the package manages. settings.md and project.md are the
19
+ // person's files and are never listed. It holds no secret.
20
+
21
+ export const MANIFEST_SCHEMA = 1;
22
+ export const MANIFEST_FILE = path.join('.e2e-qa-pilot', 'manifest.json');
23
+
24
+ // One entry per schema change: MIGRATIONS[n] turns a schema n manifest into schema n + 1.
25
+ export const MIGRATIONS = {};
26
+
27
+ export function hashText(text) {
28
+ return crypto.createHash('sha256').update(text).digest('hex');
29
+ }
30
+
31
+ function isRecord(value) {
32
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
33
+ }
34
+
35
+ export function manifestPath(project) {
36
+ return path.join(project, MANIFEST_FILE);
37
+ }
38
+
39
+ // Returns the manifest, or null when it is missing or unusable.
40
+ export function readManifest(project) {
41
+ const file = manifestPath(project);
42
+ if (!fs.existsSync(file)) return null;
43
+ try {
44
+ const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
45
+ if (!isRecord(manifest) || !isRecord(manifest.files)) return null;
46
+ if (!Number.isInteger(manifest.schema)) return null;
47
+ return {
48
+ schema: manifest.schema,
49
+ package_version: String(manifest.package_version ?? ''),
50
+ integrations: Array.isArray(manifest.integrations) ? manifest.integrations : [],
51
+ files: manifest.files,
52
+ templates: isRecord(manifest.templates) ? manifest.templates : undefined,
53
+ };
54
+ } catch {
55
+ return null;
56
+ }
57
+ }
58
+
59
+ export function writeManifest(project, manifest) {
60
+ const file = manifestPath(project);
61
+ fs.mkdirSync(path.dirname(file), { recursive: true });
62
+ fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
63
+ }
64
+
65
+ // One line for the top of a tool result when the project files came from another version.
66
+ export function versionNotice(project, packageVersion) {
67
+ const manifest = readManifest(project);
68
+ if (!manifest || manifest.package_version === packageVersion) return '';
69
+ return `Project files were installed by e2e-qa-pilot ${manifest.package_version || 'an unknown version'}; this server is ${packageVersion}. Tell the person to run \`npx e2e-qa-pilot upgrade\`.`;
70
+ }
package/src/mcp.mjs CHANGED
@@ -1,7 +1,16 @@
1
1
  import path from 'node:path';
2
2
  import fs from 'node:fs';
3
3
  import readline from 'node:readline';
4
- import { commandsDir, CATALOG, CASE_INPUT_SCHEMA, SERVER_NAME, readPackageVersion } from './kit.mjs';
4
+ import {
5
+ commandsDir,
6
+ CATALOG,
7
+ CASE_INPUT_SCHEMA,
8
+ NO_INPUT_SCHEMA,
9
+ kitRoot,
10
+ SERVER_NAME,
11
+ readPackageVersion,
12
+ } from './kit.mjs';
13
+ import { versionNotice } from './manifest.mjs';
5
14
 
6
15
  // A small stdio MCP server with no dependencies, so every line it runs can be read.
7
16
  // Tool names, descriptions, and the input schema come from kit.mjs.
@@ -13,7 +22,7 @@ import { commandsDir, CATALOG, CASE_INPUT_SCHEMA, SERVER_NAME, readPackageVersio
13
22
  const TOOLS = Object.fromEntries(
14
23
  CATALOG.map((entry) => [
15
24
  entry.tool,
16
- { command: entry.command, description: entry.description },
25
+ { command: entry.command, description: entry.description, input: entry.input ?? 'case' },
17
26
  ]),
18
27
  );
19
28
 
@@ -82,41 +91,62 @@ function sourceBlock(source) {
82
91
  ].join('\n');
83
92
  }
84
93
 
94
+ function projectFiles(projectDir, { forSetup = false } = {}) {
95
+ const settingsPath = path.join(projectDir, '.e2e-qa-pilot', 'settings.md');
96
+ const projectPath = path.join(projectDir, '.e2e-qa-pilot', 'project.md');
97
+ return {
98
+ settings: fs.existsSync(settingsPath)
99
+ ? read(settingsPath)
100
+ : `(missing: ${settingsPath}. Run \`npx e2e-qa-pilot init\` in the project.)`,
101
+ project: fs.existsSync(projectPath)
102
+ ? read(projectPath)
103
+ : forSetup
104
+ ? `(missing: .e2e-qa-pilot/project.md. Write it from this template.)\n\n${read(path.join(kitRoot, 'templates', 'project.md'))}`
105
+ : '(missing: .e2e-qa-pilot/project.md. Optional for a case run. If it would help, ask the person to run setup_project.)',
106
+ };
107
+ }
108
+
109
+ const CASE_INTRO = [
110
+ 'You do the work yourself with the tools you already have (your case tool, Playwright, GitHub, and any',
111
+ 'MCP server or CLI that .e2e-qa-pilot/project.md names).',
112
+ 'This server fetched nothing. Ask the human when a step is vague, read every screenshot yourself,',
113
+ 'and never paste a secret into the chat.',
114
+ ];
115
+
116
+ const SETUP_INTRO = [
117
+ 'No case is needed. You do the work yourself with the tools you already have',
118
+ '(file reads, git, gh, and the MCP servers connected in this editor).',
119
+ 'This server detected nothing. Never paste a secret into the chat or into these files.',
120
+ ];
121
+
85
122
  export function buildToolText(toolName, source, projectDir) {
86
123
  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'));
124
+ const setup = tool.input === 'none';
125
+ const shared = (name) => read(path.join(commandsDir, 'shared', name));
126
+ const { settings, project } = projectFiles(projectDir, { forSetup: setup });
90
127
 
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.)`;
128
+ const sections = [
129
+ ['Settings (.e2e-qa-pilot/settings.md)', settings],
130
+ ['Project file (.e2e-qa-pilot/project.md)', project],
131
+ ['Instructions', read(path.join(commandsDir, tool.command, 'SKILL.md'))],
132
+ ['Shared: project-config.md', shared('project-config.md')],
133
+ ];
134
+ if (!setup) {
135
+ sections.push(
136
+ ['Shared: workflow.md', shared('workflow.md')],
137
+ ['Shared: ready-rules.md', shared('ready-rules.md')],
138
+ ['Shared: pr-evidence.md', shared('pr-evidence.md')],
139
+ );
140
+ }
141
+
142
+ const notice = versionNotice(projectDir, readPackageVersion());
95
143
 
96
144
  return [
97
145
  `# ${SERVER_NAME}: ${toolName}`,
146
+ ...(notice ? ['', notice] : []),
98
147
  '',
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,
148
+ ...(setup ? SETUP_INTRO : [sourceBlock(source), '', ...CASE_INTRO]),
149
+ ...sections.flatMap(([title, body]) => ['', `## ${title}`, '', body]),
120
150
  ].join('\n');
121
151
  }
122
152
 
@@ -152,7 +182,7 @@ export function handleMessage(message, projectDir) {
152
182
  tools: Object.entries(TOOLS).map(([name, tool]) => ({
153
183
  name,
154
184
  description: tool.description,
155
- inputSchema: CASE_INPUT_SCHEMA,
185
+ inputSchema: tool.input === 'none' ? NO_INPUT_SCHEMA : CASE_INPUT_SCHEMA,
156
186
  })),
157
187
  },
158
188
  };
@@ -161,6 +191,21 @@ export function handleMessage(message, projectDir) {
161
191
  if (!TOOLS[name]) {
162
192
  return { error: { code: -32602, message: `Unknown tool: ${name}` } };
163
193
  }
194
+ if (TOOLS[name].input === 'none') {
195
+ const args = params?.arguments;
196
+ const empty = args === undefined || args === null || (isRecord(args) && Object.keys(args).length === 0);
197
+ if (!empty) {
198
+ return {
199
+ result: {
200
+ isError: true,
201
+ content: [{ type: 'text', text: `${name} takes no input.` }],
202
+ },
203
+ };
204
+ }
205
+ return {
206
+ result: { content: [{ type: 'text', text: buildToolText(name, null, projectDir) }] },
207
+ };
208
+ }
164
209
  const source = resolveCaseInput(params?.arguments);
165
210
  if (source.error) {
166
211
  return {
@@ -0,0 +1,17 @@
1
+ ## e2e-qa-pilot
2
+
3
+ When asked to work on a manual test case:
4
+
5
+ 1. Read `.e2e-qa-pilot/settings.md`.
6
+ 2. Read `.e2e-qa-pilot/project.md`.
7
+ 3. Follow the matching command in `.e2e-qa-pilot/processes/create-e2e/commands/`:
8
+ - `review-case`: check that a case is specific enough to assert.
9
+ - `add-from-steps` and `add-from-design`: write the spec and open the pull request.
10
+ - `setup-project`: fill in `project.md`.
11
+
12
+ Rules that always apply:
13
+
14
+ - Do not ask what those two files answer.
15
+ - Feature flags and other repositories are read-only.
16
+ - Never put a token in a file, a commit, or the chat.
17
+ - Never edit an expected result to make a test pass. A person reviews every pull request.
@@ -0,0 +1,89 @@
1
+ # Project
2
+
3
+ > Everything on this page is optional. Fill in only what your project needs and delete the rest.
4
+ > The easiest way: ask your assistant "Set up e2e-qa-pilot for this project." It reads the repository and your MCP servers and fills this file.
5
+ > Block quotes and code blocks are explanation and examples. They are not read. Write your own lines as plain text under the heading.
6
+ > Never put a token or secret here. Credentials belong in your editor's MCP configuration.
7
+ > More examples: `examples/project-files/` in the e2e-qa-pilot repository. Reference: `docs/project.md`.
8
+
9
+ ## Ticket
10
+
11
+ > Use this if your branch or commit names a ticket. Without it, the assistant never asks for an id.
12
+
13
+ ```text
14
+ Tracker: Jira
15
+ Required: yes
16
+ {ticket_id} is the full key, for example PROJ-123.
17
+ ```
18
+
19
+ ## Branch & commit
20
+
21
+ > Use this if your branches or commits follow a format, or you do not start from `main`.
22
+
23
+ ```text
24
+ Start from `develop`. Open the pull request against `develop`.
25
+ Branch: `{ticket_id}[_{case_id}]_{title_slug}`
26
+ Commit subject: `test({ticket_id}): {explanation}`
27
+ ```
28
+
29
+ > `[ ... ]` is an optional group. It is dropped, with its separator, when the placeholder inside has no value.
30
+
31
+ ## Case tool
32
+
33
+ > Use this if you pass a case id and the case lives in a tool such as Qase, TestRail, Xray, or Zephyr.
34
+
35
+ ```text
36
+ Tool: TestRail, through the `testrail` MCP server.
37
+ Fetch: use the `testrail` tool that gets a case by id.
38
+ Update: use the `testrail` tool that updates a case. Always pass the id.
39
+ The case id is optional. A pasted case has none.
40
+ ```
41
+
42
+ ## Design
43
+
44
+ > Use this if cases link to Figma frames.
45
+
46
+ ```text
47
+ Figma: on
48
+ Read a frame: use the `figma` tool that returns a frame for a node id.
49
+ ```
50
+
51
+ > With `Figma: on`, the design command runs only for a case that contains a figma.com URL.
52
+
53
+ ## Feature flags
54
+
55
+ > Use this if a feature can be switched off by a flag (GrowthBook, LaunchDarkly, Unleash, Statsig). The assistant only reads flags.
56
+
57
+ ```text
58
+ Tool: LaunchDarkly, through the `launchdarkly` MCP server. Read only.
59
+ Environment: staging.
60
+ If a flag the case needs is off, say so and stop.
61
+ ```
62
+
63
+ ## Context repos
64
+
65
+ > Use this if another repository, such as your frontend, holds the routes and test ids. The assistant reads it through `gh` and never writes to it.
66
+
67
+ ```text
68
+ Repository: `my-org/frontend`, default branch `main`. Read only.
69
+ Read routes, test ids, labels, and flag keys.
70
+ ```
71
+
72
+ ## Test layout
73
+
74
+ > Use this if the assistant cannot find your tests on its own.
75
+
76
+ ```text
77
+ Specs: `tests/e2e`
78
+ Fixture: `tests/fixture.ts`
79
+ Screenshots: `tests/screenshots`
80
+ ```
81
+
82
+ ## Rules
83
+
84
+ > Use this for anything else, in plain sentences. These cannot weaken the ready checks, the word rule, the screenshot gate, the labels, or `pr_mode`.
85
+
86
+ ```text
87
+ Locate elements by data-testid when it exists.
88
+ Name every spec file after the feature, in kebab-case.
89
+ ```
@@ -1,57 +1,28 @@
1
1
  # Settings
2
2
 
3
- ## Context
4
-
5
- ## Requirements
6
-
7
- ## Goal
3
+ > The keys every project shares. An empty value is unset: the first run asks once for the ones it needs and writes your answers here. Everything specific to this repository (ticket id, branch and commit format, case tool, Figma, feature flags, other repositories) goes in `.e2e-qa-pilot/project.md`, and a section there wins over the matching key here. Never put a token here.
8
4
 
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.
5
+ ## Context
27
6
 
28
- Keys, case tool with Figma on:
7
+ `case_tool`, `fetch_case`, and `update_case` are only for a case id. Pasted case text does not use them. Leave them empty if you have no case tool. `figma` is `on` or `off`. `read_figma` is needed only with `figma: on`.
29
8
 
30
9
  case_tool:
31
10
  fetch_case:
32
11
  update_case:
33
- figma: on
12
+ figma:
34
13
  read_figma:
35
- branch_pattern: e2e/{title_slug}
14
+
15
+ ## Requirements
16
+
36
17
  test_command:
37
18
  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
19
 
43
- Keys, case tool with Figma left off:
20
+ ## Goal
21
+
22
+ `branch_pattern` names the branch. `{title_slug}` is the case title in kebab-case. `{case_id}` is filled in only for a case id. A value without a placeholder is a literal name and puts every case on that one branch. With no value, the branch is `e2e/{title_slug}`, or `e2e/{case_id}-{title_slug}` for a case id. `pr_mode` is `create_pr_for_review` or `ask_before_pr`. A missing `pr_mode` or label uses the value shown here, without a question.
44
23
 
45
- case_tool:
46
- fetch_case:
47
- update_case:
48
- figma: off
49
- read_figma:
50
24
  branch_pattern: e2e/{title_slug}
51
- test_command:
52
- png_dir:
53
25
  pr_mode: create_pr_for_review
54
26
  pr_label_ready: e2e:ready
55
27
  pr_label_minor_text_diff: e2e:minor-text-diff
56
28
  pr_label_mismatch: e2e:mismatch
57
- -->
package/assets/logo.svg DELETED
@@ -1,12 +0,0 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="e2e-qa-pilot">
2
- <defs>
3
- <linearGradient id="pilot-bg" x1="16" y1="8" x2="112" y2="120" gradientUnits="userSpaceOnUse">
4
- <stop offset="0" stop-color="#4f46e5"/>
5
- <stop offset="0.55" stop-color="#7c3aed"/>
6
- <stop offset="1" stop-color="#06b6d4"/>
7
- </linearGradient>
8
- </defs>
9
- <rect x="4" y="4" width="120" height="120" rx="28" fill="url(#pilot-bg)"/>
10
- <path d="M34 66.5 L54.5 87 L96 40" fill="none" stroke="#ffffff" stroke-width="12" stroke-linecap="round" stroke-linejoin="round"/>
11
- <circle cx="96" cy="32" r="6" fill="#ffffff"/>
12
- </svg>