qatools-cli 1.2.18 → 1.2.20
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/context-sync.js +130 -1
- package/package.json +1 -1
- package/qatools.js +196 -14
package/context-sync.js
CHANGED
|
@@ -49,6 +49,135 @@ function renderBuiltSection(requirements, epics = []) {
|
|
|
49
49
|
return lines.join("\n");
|
|
50
50
|
}
|
|
51
51
|
|
|
52
|
+
// What qa-tools offers that a session would not think of by itself. Short on purpose: each line names
|
|
53
|
+
// the command that gives the full instructions.
|
|
54
|
+
function renderToolsSection() {
|
|
55
|
+
return [
|
|
56
|
+
"### qa-tools tools for this project",
|
|
57
|
+
"- Code exists that no requirement covers (built before qa-tools, or on the side): `qatools baseline-prompt` — reconstruct requirements from the code; a member approves them as built.",
|
|
58
|
+
"- Users should be able to request features and vote (whether or not the app already has a page for it): `qatools requests-integration-prompt` — requests, votes and comments reach qa-tools and their status (accepted / planned / released / declined) goes back to the app. See what has arrived: `qatools feature-requests`.",
|
|
59
|
+
"- Something more important must go into a sprint in progress: propose a swap (MCP `propose_sprint_plan` swaps) instead of overfilling it; a member approves.",
|
|
60
|
+
"",
|
|
61
|
+
].join("\n");
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
// Instructions for connecting an app's own feature-request page to qa-tools (signals.user-feature-requests)
|
|
65
|
+
const FEATURE_REQUESTS_URL = "https://us-central1-qatools-app.cloudfunctions.net/featureRequests";
|
|
66
|
+
const FENCE = "```";
|
|
67
|
+
function requestsIntegrationPrompt(projectName) {
|
|
68
|
+
return [
|
|
69
|
+
`# Connect this app's feature requests to qa-tools${projectName ? ` (project "${projectName}")` : ""}`,
|
|
70
|
+
"",
|
|
71
|
+
"Users request features and vote on each other's requests. qa-tools gets the requests and votes, members link them",
|
|
72
|
+
"to requirements, and the app shows what happened to each request — so users see that their votes matter.",
|
|
73
|
+
"",
|
|
74
|
+
"Two ways, depending on the app:",
|
|
75
|
+
"- A. The app already stores requests and votes (its own collection/table and voting): keep it, add a sync (steps 3A).",
|
|
76
|
+
"- B. The app has no request store: qa-tools keeps the requests, votes and comments; the app only shows a thin page",
|
|
77
|
+
" that its server builds on the calls list / create / vote / comment / comments (steps 3B). No database, no voting",
|
|
78
|
+
" logic and no sync in the app.",
|
|
79
|
+
"",
|
|
80
|
+
"## Procedure",
|
|
81
|
+
"1. Find out which: look for where the app keeps requests and votes (collection/table, fields) and the page that",
|
|
82
|
+
" shows them. Read the code. If there is none, it is B.",
|
|
83
|
+
" For B the page is new: write a requirement for it first (Given/When/Then in the project's language) and let the",
|
|
84
|
+
" user approve it before you build — e.g. `qatools requirement-create`.",
|
|
85
|
+
"2. Ask the user for the feature-request key. The project owner creates it in qa-tools: Members → Requests from the",
|
|
86
|
+
" app → Create key. It starts with `fr-`, is shown once, and can only send and read requests, votes and comments.",
|
|
87
|
+
" Keep it server-side as a secret named QATOOLS_FEATURE_REQUEST_KEY. Never in client code, never in the repo:",
|
|
88
|
+
" the browser calls the app's own server, which calls qa-tools.",
|
|
89
|
+
"3B. (no store of its own) Add server routes that pass the logged-in user's id to qa-tools — list, create, vote,",
|
|
90
|
+
" comment, comments — and a page on them: the requests most votes first, with votes, status, comments, a vote button",
|
|
91
|
+
" (voted: true shows it as given; vote again with vote:false takes it back), a form for a new request, and the comment",
|
|
92
|
+
" thread. Send the user's display name as userName with comments. Then go to step 4.",
|
|
93
|
+
"3A. (own store) Add a scheduled server job (every 15 minutes is enough) that:",
|
|
94
|
+
" - sends every request with its current votes: action \"upsert\", at most 200 per call. The app's own id",
|
|
95
|
+
" identifies a request, so sending all of them every time is fine — it updates, it does not duplicate;",
|
|
96
|
+
" - reads the status of the same ids: action \"status\", at most 500 per call;",
|
|
97
|
+
" - stores each status on the app's own request record (e.g. a field qaStatus).",
|
|
98
|
+
"4. Show the status on the request page, in the app's language, with the votes: new → received; accepted → accepted",
|
|
99
|
+
" (it is linked to a requirement); planned → the release name and its planned date (releaseDate); released →",
|
|
100
|
+
" released; declined → declined with the reason (members write it for the users).",
|
|
101
|
+
"5. Verify it yourself before you say it works: (A) run the job once, or (B) create a request and vote through your",
|
|
102
|
+
" own routes; then `qatools feature-requests` must list the requests with their votes, and the app must show",
|
|
103
|
+
" status \"new\". Report what you saw. The user then links one request to a planned requirement in qa-tools; after",
|
|
104
|
+
" that (and the next sync for A) its status must be \"planned\" with the release and date.",
|
|
105
|
+
"6. If the app's requirements in qa-tools do not cover the request page or this sync, say so — the user decides",
|
|
106
|
+
" whether to add requirements.",
|
|
107
|
+
"",
|
|
108
|
+
"## API",
|
|
109
|
+
`POST ${FEATURE_REQUESTS_URL}`,
|
|
110
|
+
"Headers: Content-Type: application/json, Authorization: Bearer <fr- key>",
|
|
111
|
+
"",
|
|
112
|
+
"Send requests:",
|
|
113
|
+
' { "action": "upsert", "requests": [ { "id": "42", "title": "Dark mode", "description": "…", "votes": 15, "url": "https://…" } ] }',
|
|
114
|
+
' → { "created": 1, "updated": 0, "refused": [] } (refused: [{ "id": "", "reason": "id and title are required" }])',
|
|
115
|
+
"",
|
|
116
|
+
"Read status (A):",
|
|
117
|
+
' { "action": "status", "ids": ["42", "43"] }',
|
|
118
|
+
' → { "statuses": [ { "id": "42", "votes": 15, "status": "planned", "sprint": "Release 4.1", "releaseDate": "2026-11-18" },',
|
|
119
|
+
' { "id": "43", "votes": 2, "status": "declined", "reason": "…" } ] }',
|
|
120
|
+
" status is one of: new, accepted, planned, released, declined, unknown (never sent)",
|
|
121
|
+
"",
|
|
122
|
+
"Kept by qa-tools (B) — userId is the app's id for the user who acts; qa-tools stores only a hash of it:",
|
|
123
|
+
' { "action": "list", "userId": "u2" }',
|
|
124
|
+
' → { "requests": [ { "id": "qa-…", "title": "…", "description": "…", "votes": 3, "comments": 1, "voted": true,',
|
|
125
|
+
' "status": "planned", "sprint": "Release 4.1", "releaseDate": "2026-11-18" } ] } (most votes first)',
|
|
126
|
+
' { "action": "create", "userId": "u1", "title": "Dark mode", "description": "…" } → { "request": { …, "votes": 1, "voted": true } }',
|
|
127
|
+
' { "action": "vote", "userId": "u2", "id": "qa-…" } → { "id": "qa-…", "votes": 2, "voted": true }',
|
|
128
|
+
' { "action": "vote", "userId": "u2", "id": "qa-…", "vote": false } → takes the vote back; one vote per user and request',
|
|
129
|
+
' { "action": "comment", "userId": "u2", "userName": "Anna", "id": "qa-…", "text": "…" }',
|
|
130
|
+
' { "action": "comments", "id": "qa-…" } → { "comments": [ { "author": "Anna", "team": false, "text": "…", "at": "…" },',
|
|
131
|
+
' { "author": "team", "team": true, "text": "…", "at": "…" } ] }',
|
|
132
|
+
" Replies from the project's members come back with author \"team\". Votes on requests the app syncs itself (A) are",
|
|
133
|
+
" refused (409) — their votes come from the app.",
|
|
134
|
+
"",
|
|
135
|
+
"Errors: 401 missing key, 403 wrong or revoked key, 400 bad body (e.g. no userId, no title, title over 300",
|
|
136
|
+
"characters), 404 unknown request, 409 vote on a synced request, 429 more than 600 calls a minute from one server.",
|
|
137
|
+
"",
|
|
138
|
+
"## Example B (Node/Express routes in the app's server — adapt to the app's framework and auth)",
|
|
139
|
+
FENCE + "js",
|
|
140
|
+
`const QA = "${FEATURE_REQUESTS_URL}";`,
|
|
141
|
+
"const qa = async (body) => {",
|
|
142
|
+
' const res = await fetch(QA, { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + process.env.QATOOLS_FEATURE_REQUEST_KEY }, body: JSON.stringify(body) });',
|
|
143
|
+
" const json = await res.json();",
|
|
144
|
+
' if (!res.ok) throw Object.assign(new Error(json.error), { status: res.status });',
|
|
145
|
+
" return json;",
|
|
146
|
+
"};",
|
|
147
|
+
"// req.user is the app's logged-in user",
|
|
148
|
+
'app.get("/api/requests", async (req, res) => res.json(await qa({ action: "list", userId: req.user.id })));',
|
|
149
|
+
'app.post("/api/requests", async (req, res) => res.json(await qa({ action: "create", userId: req.user.id, title: req.body.title, description: req.body.description })));',
|
|
150
|
+
'app.post("/api/requests/:id/vote", async (req, res) => res.json(await qa({ action: "vote", userId: req.user.id, id: req.params.id, vote: req.body.vote !== false })));',
|
|
151
|
+
'app.get("/api/requests/:id/comments", async (req, res) => res.json(await qa({ action: "comments", id: req.params.id })));',
|
|
152
|
+
'app.post("/api/requests/:id/comments", async (req, res) => res.json(await qa({ action: "comment", userId: req.user.id, userName: req.user.name, id: req.params.id, text: req.body.text })));',
|
|
153
|
+
FENCE,
|
|
154
|
+
"",
|
|
155
|
+
"## Example A (Node, Firebase scheduled function — adapt names to the app)",
|
|
156
|
+
FENCE + "js",
|
|
157
|
+
'const { onSchedule } = require("firebase-functions/v2/scheduler");',
|
|
158
|
+
'const { defineSecret } = require("firebase-functions/params");',
|
|
159
|
+
'const KEY = defineSecret("QATOOLS_FEATURE_REQUEST_KEY");',
|
|
160
|
+
`const QA = "${FEATURE_REQUESTS_URL}";`,
|
|
161
|
+
"",
|
|
162
|
+
'exports.syncRequestsToQaTools = onSchedule({ schedule: "every 15 minutes", secrets: [KEY] }, async () => {',
|
|
163
|
+
" const call = async (body) => {",
|
|
164
|
+
' const res = await fetch(QA, { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + KEY.value() }, body: JSON.stringify(body) });',
|
|
165
|
+
' if (!res.ok) throw new Error("qa-tools " + res.status + ": " + (await res.json()).error);',
|
|
166
|
+
" return res.json();",
|
|
167
|
+
" };",
|
|
168
|
+
' const snap = await db.collection("featureRequests").get();',
|
|
169
|
+
' const reqs = snap.docs.map(d => ({ id: d.id, title: d.data().title, description: d.data().description || "", votes: d.data().votes || 0 }));',
|
|
170
|
+
' for (let i = 0; i < reqs.length; i += 200) await call({ action: "upsert", requests: reqs.slice(i, i + 200) });',
|
|
171
|
+
" for (let i = 0; i < reqs.length; i += 500) {",
|
|
172
|
+
' const { statuses } = await call({ action: "status", ids: reqs.slice(i, i + 500).map(r => r.id) });',
|
|
173
|
+
' await Promise.all(statuses.map(s => db.doc("featureRequests/" + s.id).update({ qaStatus: s })));',
|
|
174
|
+
" }",
|
|
175
|
+
"});",
|
|
176
|
+
FENCE,
|
|
177
|
+
"",
|
|
178
|
+
].join("\n");
|
|
179
|
+
}
|
|
180
|
+
|
|
52
181
|
// Replace the synced block in a file's text, or append it. Text outside the block is kept as is.
|
|
53
182
|
function spliceBlock(existing, md) {
|
|
54
183
|
const block = `${BEGIN_MARKER}\n${md}\n${END_MARKER}`;
|
|
@@ -65,4 +194,4 @@ function spliceBlock(existing, md) {
|
|
|
65
194
|
const withoutSyncTime = (text) => String(text).replace(/<!-- Last synced: [^>]*-->/g, "<!-- Last synced -->").replace(/\r\n/g, "\n");
|
|
66
195
|
const sameContent = (a, b) => withoutSyncTime(a) === withoutSyncTime(b);
|
|
67
196
|
|
|
68
|
-
module.exports = { BEGIN_MARKER, END_MARKER, renderBuiltSection, spliceBlock, sameContent };
|
|
197
|
+
module.exports = { BEGIN_MARKER, END_MARKER, renderBuiltSection, renderToolsSection, requestsIntegrationPrompt, spliceBlock, sameContent };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "qatools-cli",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.20",
|
|
4
4
|
"description": "CLI for QA Tools — requirements, epics, sprints, sessions, App Context sync, project agenda. The companion to qa-tools.com.",
|
|
5
5
|
"scripts": {
|
|
6
6
|
"release": "npm version patch --no-git-tag-version && npm publish",
|
package/qatools.js
CHANGED
|
@@ -873,6 +873,106 @@ program
|
|
|
873
873
|
process.exit(0);
|
|
874
874
|
});
|
|
875
875
|
|
|
876
|
+
// signals.user-feature-requests: connect an app's own request page, and see what has arrived
|
|
877
|
+
program
|
|
878
|
+
.command("requests-integration-prompt")
|
|
879
|
+
.description("Print the procedure for connecting this app's feature-request page to qa-tools (requests and votes in, status back)")
|
|
880
|
+
.option("--project <id>", "Project ID (default: the configured one)")
|
|
881
|
+
.action((options) => {
|
|
882
|
+
// No login needed — it only prints text. Same text as the MCP tool requests_integration_prompt.
|
|
883
|
+
const creds = getCredentials();
|
|
884
|
+
const name = options.project ? "" : (creds?.projectName || "");
|
|
885
|
+
console.log(require("./context-sync").requestsIntegrationPrompt(name));
|
|
886
|
+
process.exit(0);
|
|
887
|
+
});
|
|
888
|
+
|
|
889
|
+
program
|
|
890
|
+
.command("feature-requests")
|
|
891
|
+
.description("List the requests from the app's users that have reached qa-tools, most votes first")
|
|
892
|
+
.option("--state <state>", "Only new, linked or declined")
|
|
893
|
+
.option("--json", "Output as JSON")
|
|
894
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
895
|
+
.option("-e, --email <email>", "Login email")
|
|
896
|
+
.option("-p, --password <password>", "Login password")
|
|
897
|
+
.action(async (options) => {
|
|
898
|
+
await authenticate(options);
|
|
899
|
+
const projectId = options.project || getCredentials()?.projectId;
|
|
900
|
+
if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
|
|
901
|
+
try {
|
|
902
|
+
let { requests } = (await httpsCallable(functions, "listFeatureRequests")({ projectId })).data;
|
|
903
|
+
if (options.state) requests = requests.filter(r => r.state === options.state);
|
|
904
|
+
if (options.json) { console.log(JSON.stringify(requests, null, 2)); process.exit(0); }
|
|
905
|
+
if (!requests.length) { console.log("No requests from users yet. Connect the app: qatools requests-integration-prompt"); process.exit(0); }
|
|
906
|
+
console.log(`${requests.length} request(s):\n`);
|
|
907
|
+
for (const r of requests) {
|
|
908
|
+
console.log(` ▲ ${String(r.votes || 0).padStart(4)} [${r.state}] ${r.title} (app id ${r.externalId}${r.requirementId ? `, requirement ${r.requirementId}` : ""})`);
|
|
909
|
+
}
|
|
910
|
+
process.exit(0);
|
|
911
|
+
} catch (e) {
|
|
912
|
+
console.error("Failed to list requests:", e.message);
|
|
913
|
+
process.exit(1);
|
|
914
|
+
}
|
|
915
|
+
});
|
|
916
|
+
|
|
917
|
+
// requirements.baseline-from-code: reconstruct requirements for what is already built
|
|
918
|
+
program
|
|
919
|
+
.command("baseline-prompt")
|
|
920
|
+
.description("Print the procedure for reconstructing requirements from existing code, with the project's language and all existing requirements")
|
|
921
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
922
|
+
.option("-e, --email <email>", "Login email")
|
|
923
|
+
.option("-p, --password <password>", "Login password")
|
|
924
|
+
.action(async (options) => {
|
|
925
|
+
await authenticate(options);
|
|
926
|
+
const projectId = options.project || getCredentials()?.projectId;
|
|
927
|
+
if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
|
|
928
|
+
try {
|
|
929
|
+
const { data } = await httpsCallable(functions, "getBaselinePrompt")({ projectId });
|
|
930
|
+
console.log(data.prompt);
|
|
931
|
+
process.exit(0);
|
|
932
|
+
} catch (e) {
|
|
933
|
+
console.error("Failed to get the baseline prompt:", e.message);
|
|
934
|
+
process.exit(1);
|
|
935
|
+
}
|
|
936
|
+
});
|
|
937
|
+
|
|
938
|
+
program
|
|
939
|
+
.command("baseline-upload")
|
|
940
|
+
.description("Upload requirements reconstructed from code (JSON array with key, title, acceptanceCriteria, files, commits). They are saved as drafts for a member to approve as built.")
|
|
941
|
+
.requiredOption("-f, --file <path>", "JSON file: an array of reconstructed requirements")
|
|
942
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
943
|
+
.option("-e, --email <email>", "Login email")
|
|
944
|
+
.option("-p, --password <password>", "Login password")
|
|
945
|
+
.action(async (options) => {
|
|
946
|
+
let requirements;
|
|
947
|
+
try {
|
|
948
|
+
requirements = JSON.parse(fs.readFileSync(options.file, "utf8"));
|
|
949
|
+
} catch (e) {
|
|
950
|
+
console.error(`Could not read ${options.file}: ${e.message}`);
|
|
951
|
+
process.exit(1);
|
|
952
|
+
}
|
|
953
|
+
if (!Array.isArray(requirements)) { console.error("The file must hold a JSON array of requirements"); process.exit(1); }
|
|
954
|
+
await authenticate(options);
|
|
955
|
+
const projectId = options.project || getCredentials()?.projectId;
|
|
956
|
+
if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
|
|
957
|
+
try {
|
|
958
|
+
const { data } = await httpsCallable(functions, "uploadBaselineRequirements")({ projectId, requirements });
|
|
959
|
+
console.log(`Saved ${data.saved.length} reconstructed requirement(s) as drafts.`);
|
|
960
|
+
if (data.duplicates.length) {
|
|
961
|
+
console.log(`Skipped ${data.duplicates.length} duplicate(s):`);
|
|
962
|
+
for (const d of data.duplicates) console.log(` - ${d.key} (same ${d.matchedOn} as ${d.matches})`);
|
|
963
|
+
}
|
|
964
|
+
if (data.refused.length) {
|
|
965
|
+
console.log(`Refused ${data.refused.length}:`);
|
|
966
|
+
for (const r of data.refused) console.log(` - ${r.key}: ${r.reason}`);
|
|
967
|
+
}
|
|
968
|
+
if (data.saved.length) console.log("A member approves them as built in the web app: Requirements → filter panel → Reconstructed from code.");
|
|
969
|
+
process.exit(data.refused.length ? 2 : 0);
|
|
970
|
+
} catch (e) {
|
|
971
|
+
console.error("Upload failed:", e.message);
|
|
972
|
+
process.exit(1);
|
|
973
|
+
}
|
|
974
|
+
});
|
|
975
|
+
|
|
876
976
|
program
|
|
877
977
|
.command("plan-proposals")
|
|
878
978
|
.description("List sprint-plan proposals (pending ones are approved in the web app: Sprints → Plan proposals)")
|
|
@@ -1339,7 +1439,8 @@ async function renderSyncedContext(ctx, projectId, systemAiRules) {
|
|
|
1339
1439
|
httpsCallable(functions, "listRequirements")({ projectId, status: null }),
|
|
1340
1440
|
httpsCallable(functions, "listEpics")({ projectId }),
|
|
1341
1441
|
]);
|
|
1342
|
-
|
|
1442
|
+
const { renderToolsSection } = require("./context-sync");
|
|
1443
|
+
return renderAppContextMarkdown(ctx, projectId, systemAiRules) + "\n" + renderToolsSection() + "\n" + renderBuiltSection(reqRes.data.requirements || [], epicRes.data.epics || []);
|
|
1343
1444
|
}
|
|
1344
1445
|
|
|
1345
1446
|
function renderAppContextMarkdown(ctx, projectId, systemAiRules) {
|
|
@@ -1548,6 +1649,7 @@ program
|
|
|
1548
1649
|
.option("--title <text>", "Set title")
|
|
1549
1650
|
.option("--description <text>", "Set description")
|
|
1550
1651
|
.option("--ac <text>", "Set acceptance criteria")
|
|
1652
|
+
.option("--points <n>", "Set size in points: 1, 2, 3, 5 or 8 (empty string clears). Not for non-functional requirements.")
|
|
1551
1653
|
.option("--project <id>", "Target project ID (overrides default; requires access to that project)")
|
|
1552
1654
|
.option("-e, --email <email>", "Login email")
|
|
1553
1655
|
.option("-p, --password <password>", "Login password")
|
|
@@ -1578,6 +1680,7 @@ program
|
|
|
1578
1680
|
if (options.title) u.title = options.title;
|
|
1579
1681
|
if (options.description) u.description = options.description;
|
|
1580
1682
|
if (options.ac) u.acceptanceCriteria = options.ac;
|
|
1683
|
+
if (options.points !== undefined) u.points = options.points === "" ? null : Number(options.points);
|
|
1581
1684
|
updates[options.id] = u;
|
|
1582
1685
|
if (options.evidence) evidenceById[options.id] = options.evidence;
|
|
1583
1686
|
} else {
|
|
@@ -2655,6 +2758,11 @@ App Context → Epics → Requirements → Sprint → Implementation → Test
|
|
|
2655
2758
|
- Implement EXACTLY what the requirement says — ask if unclear
|
|
2656
2759
|
- If the requirement is ambiguous, create a GAP — don't guess
|
|
2657
2760
|
- Include commitId when uploading analysis
|
|
2761
|
+
|
|
2762
|
+
## Tools you may not think of
|
|
2763
|
+
- Code exists that no requirement covers (built before qa-tools, or on the side): \`qatools baseline-prompt\` — reconstruct requirements from the code; a member approves them as built.
|
|
2764
|
+
- Users should be able to request features and vote (whether or not the app already has a page for it): \`qatools requests-integration-prompt\` — requests, votes and comments reach qa-tools and their status goes back to the app. See what has arrived: \`qatools feature-requests\`.
|
|
2765
|
+
- Something more important must go into a sprint in progress: propose a swap instead of overfilling it; a member approves.
|
|
2658
2766
|
`,
|
|
2659
2767
|
|
|
2660
2768
|
"qa-test-generator.md": `---
|
|
@@ -2782,7 +2890,7 @@ If the qa-tools MCP server (\`qatools mcp\`) is available, use its tools and the
|
|
|
2782
2890
|
\`qatools sprints\`
|
|
2783
2891
|
\`qatools epics -o epics.json\` (dependsOn = build order)
|
|
2784
2892
|
\`qatools requirements --status approved --json\`
|
|
2785
|
-
Capacity:
|
|
2893
|
+
Capacity (MCP: \`sprint_velocity\` → capacity): the average done points of the last three completed sprints with points; without that history it is counted in requirements, and you say so. With no history at all, say so and propose a conservative number.
|
|
2786
2894
|
|
|
2787
2895
|
2. Draft a proposal:
|
|
2788
2896
|
- Only approved, functional requirements without a sprint are candidates. Continuous (non-functional) requirements are never planned — they are checked against every sprint.
|
|
@@ -2790,10 +2898,10 @@ If the qa-tools MCP server (\`qatools mcp\`) is available, use its tools and the
|
|
|
2790
2898
|
- Carry-over: approved or in-progress requirements in an overdue sprint (end date passed, not completed) may be proposed for a move to an open sprint — they keep status and assignee. Never move requirements out of a sprint that has not passed its end date.
|
|
2791
2899
|
- An epic's requirements never go before the requirements of the epics it dependsOn.
|
|
2792
2900
|
- Priority 1 first, then epic priority.
|
|
2793
|
-
- Per sprint:
|
|
2901
|
+
- Per sprint: up to the capacity, counting what is already in the sprint. Requirements without points get proposed points (1, 2, 3, 5 or 8 — propose splitting anything bigger); mark them as proposed.
|
|
2794
2902
|
- If existing sprints don't fit, propose new ones (name + end date) — don't create them yet.
|
|
2795
2903
|
|
|
2796
|
-
3. Present the proposal and WAIT: a table of sprint | requirement key | title | reason (priority / epic dependency / capacity), plus what you left out and why, and any dependency conflicts. Change nothing until the user approves.
|
|
2904
|
+
3. Present the proposal and WAIT: a table of sprint | requirement key | title | points | reason (priority / epic dependency / capacity), with each sprint's total points against the capacity, plus what you left out and why, and any dependency conflicts. Change nothing until the user approves.
|
|
2797
2905
|
|
|
2798
2906
|
4. Apply after approval:
|
|
2799
2907
|
\`qatools sprint-create --name "Release 4.1" --end 2026-12-15\`
|
|
@@ -3698,9 +3806,10 @@ const mcpTools = [
|
|
|
3698
3806
|
sprintId: mcpStr("Sprint ID to plan it in"),
|
|
3699
3807
|
status: mcpStr("Initial status (default draft)", { enum: MCP_REQ_STATUSES }),
|
|
3700
3808
|
force: mcpBool("Skip the semantic similarity check"),
|
|
3809
|
+
points: { type: "integer", enum: [1, 2, 3, 5, 8], description: "Size in points. Split anything bigger than 8. Not for non-functional requirements." },
|
|
3701
3810
|
version: mcpInt("New version of an existing key (e.g. 2). Then set the old version to superseded with update_requirement."),
|
|
3702
3811
|
}, ["key", "title"]),
|
|
3703
|
-
run: async (a) => mcpCall("createRequirement", { projectId: a.projectId, ...mcpPick(a, ["key", "title", "description", "acceptanceCriteria", "negativeCriteria", "type", "priority", "category", "epicKey", "sprintId", "status", "force", "version"]) }),
|
|
3812
|
+
run: async (a) => mcpCall("createRequirement", { projectId: a.projectId, ...mcpPick(a, ["key", "title", "description", "acceptanceCriteria", "negativeCriteria", "type", "priority", "category", "epicKey", "sprintId", "status", "force", "version", "points"]) }),
|
|
3704
3813
|
},
|
|
3705
3814
|
{
|
|
3706
3815
|
name: "update_requirement",
|
|
@@ -3716,11 +3825,12 @@ const mcpTools = [
|
|
|
3716
3825
|
title: mcpStr("Title"),
|
|
3717
3826
|
description: mcpStr("Description"),
|
|
3718
3827
|
acceptanceCriteria: mcpStr("Acceptance criteria"),
|
|
3828
|
+
points: { type: ["integer", "null"], enum: [1, 2, 3, 5, 8, null], description: "Size in points (null clears). Split anything bigger than 8. Not for non-functional requirements." },
|
|
3719
3829
|
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3720
3830
|
commit: mcpStr("Commit the evidence was verified on. Default: git HEAD of the server's working directory; empty string to leave it out"),
|
|
3721
3831
|
}, ["requirementId"]),
|
|
3722
3832
|
run: async (a) => {
|
|
3723
|
-
const updates = mcpPick(a, ["status", "assignedTo", "epicKey", "sprintId", "type", "title", "description", "acceptanceCriteria"]);
|
|
3833
|
+
const updates = mcpPick(a, ["status", "assignedTo", "epicKey", "sprintId", "type", "title", "description", "acceptanceCriteria", "points"]);
|
|
3724
3834
|
if (Object.keys(updates).length === 0) throw new McpToolError("No fields to update.");
|
|
3725
3835
|
const evidenceById = a.evidence ? { [a.requirementId]: a.evidence } : {};
|
|
3726
3836
|
if (requirementEvidenceViolations({ [a.requirementId]: updates }, evidenceById).length > 0) {
|
|
@@ -3790,7 +3900,7 @@ const mcpTools = [
|
|
|
3790
3900
|
},
|
|
3791
3901
|
{
|
|
3792
3902
|
name: "sprint_velocity",
|
|
3793
|
-
description: "Planning capacity: per completed sprint, how many requirements were planned and done, plus what is already planned in each open sprint. Completed sprints use the numbers stored when they were completed (fromSnapshot true); older ones are counted from today's statuses (fromSnapshot false). averageCompletionRate = average share of planned requirements that got done.",
|
|
3903
|
+
description: "Planning capacity: per completed sprint, how many requirements were planned and done, plus what is already planned in each open sprint. Completed sprints use the numbers stored when they were completed (fromSnapshot true); older ones are counted from today's statuses (fromSnapshot false). averageCompletionRate = average share of planned requirements that got done. capacity (sprint.requirement-points) = average done points of the last three completed sprints with points, or — without such history — done requirements; plan each sprint up to it, counting what it already holds (openSprints[].points).",
|
|
3794
3904
|
inputSchema: mcpSchema(),
|
|
3795
3905
|
run: async (a) => {
|
|
3796
3906
|
const [{ sprints }, { requirements }] = await Promise.all([
|
|
@@ -3803,21 +3913,35 @@ const mcpTools = [
|
|
|
3803
3913
|
const base = { id: s.id, name: s.name, status: s.status, startDate: s.startDate || "", releaseDate: s.releaseDate || "" };
|
|
3804
3914
|
// sprint.completion-snapshot: completing moves the unfinished out, so only the stored numbers show what was planned.
|
|
3805
3915
|
if (s.status === "completed" && s.completionStats) {
|
|
3806
|
-
|
|
3916
|
+
const cs = s.completionStats;
|
|
3917
|
+
return { ...base, planned: cs.planned, done: cs.done, moved: cs.moved, fromSnapshot: true, completedAt: cs.completedAt || "",
|
|
3918
|
+
...(typeof cs.donePoints === "number" ? { plannedPoints: cs.plannedPoints, donePoints: cs.donePoints } : {}) };
|
|
3807
3919
|
}
|
|
3808
3920
|
const reqs = active.filter(r => r.sprintId === s.id);
|
|
3809
|
-
return { ...base, planned: reqs.length, done: reqs.filter(r => DONE.has(r.status)).length,
|
|
3921
|
+
return { ...base, planned: reqs.length, done: reqs.filter(r => DONE.has(r.status)).length,
|
|
3922
|
+
points: reqs.reduce((n, r) => n + (r.points || 0), 0), withoutPoints: reqs.filter(r => !r.points).length,
|
|
3923
|
+
...(s.status === "completed" ? { fromSnapshot: false } : {}) };
|
|
3810
3924
|
};
|
|
3811
3925
|
const completed = sprints.filter(s => s.status === "completed").map(row);
|
|
3812
3926
|
const withWork = completed.filter(s => s.planned > 0);
|
|
3813
3927
|
const avg = withWork.length ? withWork.reduce((n, s) => n + s.done, 0) / withWork.length : null;
|
|
3814
3928
|
const rate = withWork.length ? withWork.reduce((n, s) => n + s.done / s.planned, 0) / withWork.length : null;
|
|
3929
|
+
// Same rule as the web app (sprint-capacity.ts): last three completed sprints with points, else done requirements
|
|
3930
|
+
const recent = [...completed].filter(s => s.fromSnapshot).sort((x, y) => (y.completedAt || "").localeCompare(x.completedAt || ""));
|
|
3931
|
+
const pointed = recent.filter(s => typeof s.donePoints === "number").slice(0, 3);
|
|
3932
|
+
const basis = pointed.length ? pointed : recent.slice(0, 3);
|
|
3933
|
+
const capacity = basis.length
|
|
3934
|
+
? { unit: pointed.length ? "points" : "requirements", value: Math.round(basis.reduce((n, s) => n + (pointed.length ? s.donePoints : s.done), 0) / basis.length), basedOn: basis.length,
|
|
3935
|
+
...(pointed.length ? {} : { note: "No completed sprint has points yet — capacity is counted in requirements" }) }
|
|
3936
|
+
: null;
|
|
3815
3937
|
return {
|
|
3938
|
+
capacity,
|
|
3816
3939
|
completedSprints: completed,
|
|
3817
3940
|
averageDonePerCompletedSprint: avg === null ? null : Math.round(avg * 10) / 10,
|
|
3818
3941
|
averageCompletionRate: rate === null ? null : Math.round(rate * 100) / 100,
|
|
3819
3942
|
openSprints: sprints.filter(s => s.status !== "completed").map(row),
|
|
3820
3943
|
unplannedApprovedRequirements: active.filter(r => r.status === "approved" && !r.sprintId).length,
|
|
3944
|
+
unplannedApprovedWithoutPoints: active.filter(r => r.status === "approved" && !r.sprintId && r.type !== "non-functional" && !r.points).length,
|
|
3821
3945
|
};
|
|
3822
3946
|
},
|
|
3823
3947
|
},
|
|
@@ -3839,6 +3963,7 @@ const mcpTools = [
|
|
|
3839
3963
|
reason: mcpStr("Why this requirement goes in this sprint"),
|
|
3840
3964
|
selfVerification: mcpStr("How you will verify it yourself, e.g. 'unit tests for X + API call Y' (sprint.ai-planning-self-verification)"),
|
|
3841
3965
|
manualOnly: { type: "boolean", description: "true when you cannot verify it yourself at all — then testProtocols must have a test for it" },
|
|
3966
|
+
points: { type: "integer", enum: [1, 2, 3, 5, 8], description: "Proposed size for a requirement that has no points yet (ignored when it has); approving the row sets it" },
|
|
3842
3967
|
},
|
|
3843
3968
|
required: ["requirementId", "reason"],
|
|
3844
3969
|
additionalProperties: false,
|
|
@@ -3906,9 +4031,25 @@ const mcpTools = [
|
|
|
3906
4031
|
additionalProperties: false,
|
|
3907
4032
|
},
|
|
3908
4033
|
},
|
|
3909
|
-
|
|
4034
|
+
swaps: {
|
|
4035
|
+
type: "array",
|
|
4036
|
+
description: "sprint.mid-release-swap: take a requirement into a sprint that is in progress and move not-started (approved) requirements out to the next open sprint so it fits its capacity. Never move out one that is in progress or done, or one a staying requirement depends on through its epic. outRequirementIds may be empty to keep the sprint over capacity — say why. A requirement may appear in items or in one swap, not both.",
|
|
4037
|
+
items: {
|
|
4038
|
+
type: "object",
|
|
4039
|
+
properties: {
|
|
4040
|
+
sprintId: mcpStr("Sprint in progress to take the requirement into"),
|
|
4041
|
+
inRequirementId: mcpStr("Requirement taken in (approved or in progress)"),
|
|
4042
|
+
outRequirementIds: mcpStrArray("Requirements moved out (approved, in that sprint)"),
|
|
4043
|
+
reason: mcpStr("Why the change is worth it"),
|
|
4044
|
+
},
|
|
4045
|
+
required: ["sprintId", "inRequirementId", "outRequirementIds", "reason"],
|
|
4046
|
+
additionalProperties: false,
|
|
4047
|
+
},
|
|
4048
|
+
},
|
|
4049
|
+
}, []),
|
|
3910
4050
|
run: async (a) => {
|
|
3911
|
-
|
|
4051
|
+
if (!a.items?.length && !a.swaps?.length) throw new McpToolError("Give items, swaps or both.");
|
|
4052
|
+
const r = await mcpCall("createPlanProposal", { projectId: a.projectId, ...mcpPick(a, ["goal", "summary", "items", "newSprints", "omitted", "testProtocols", "swaps"]) });
|
|
3912
4053
|
return { ...r, next: "Pending. A project member approves or rejects it in qa-tools under Sprints → Plan proposals." };
|
|
3913
4054
|
},
|
|
3914
4055
|
},
|
|
@@ -4061,6 +4202,44 @@ const mcpTools = [
|
|
|
4061
4202
|
inputSchema: mcpSchema({ since: mcpStr("Range start: a git ref"), sprint: mcpStr("Range start: this sprint's start date (id or name)"), flag: { type: "boolean", description: "Record the risk in qa-tools" } }),
|
|
4062
4203
|
run: async (a) => runImpact({ projectId: a.projectId || getCredentials()?.projectId, since: a.since, sprint: a.sprint, flag: !!a.flag }),
|
|
4063
4204
|
},
|
|
4205
|
+
{
|
|
4206
|
+
name: "list_feature_requests",
|
|
4207
|
+
description: "Requests from the app's users (signals.user-feature-requests), most votes first: title, votes, state (new / linked / declined) and the linked requirementId. Linked requirements also carry requestVotes in list_requirements. Members act on them in the web app.",
|
|
4208
|
+
inputSchema: mcpSchema(),
|
|
4209
|
+
run: async (a) => (await mcpCall("listFeatureRequests", { projectId: a.projectId })).requests,
|
|
4210
|
+
},
|
|
4211
|
+
{
|
|
4212
|
+
name: "requests_integration_prompt",
|
|
4213
|
+
description: "Procedure, API and example code for connecting this app's own feature-request page to qa-tools: requests and votes in, status (planned / released / declined) back to the app. Use when the app has a page where users request features or vote.",
|
|
4214
|
+
inputSchema: mcpSchema(),
|
|
4215
|
+
run: async () => require("./context-sync").requestsIntegrationPrompt(getCredentials()?.projectName || ""),
|
|
4216
|
+
},
|
|
4217
|
+
{
|
|
4218
|
+
name: "baseline_prompt",
|
|
4219
|
+
description: "Procedure for reconstructing requirements for what is already built (requirements.baseline-from-code), with the project's language, its epics and all existing requirements. Use when code exists that qa-tools has no requirements for.",
|
|
4220
|
+
inputSchema: mcpSchema(),
|
|
4221
|
+
run: async (a) => (await mcpCall("getBaselinePrompt", { projectId: a.projectId })).prompt,
|
|
4222
|
+
},
|
|
4223
|
+
{
|
|
4224
|
+
name: "upload_baseline",
|
|
4225
|
+
description: "Upload requirements reconstructed from code. Each needs key, title, acceptanceCriteria (Given/When/Then in the project's language) and at least one file or commit where it is built. Saved as drafts marked as reconstructed; duplicates of existing requirements are skipped. A member approves them as built in the web app — you never approve them yourself.",
|
|
4226
|
+
inputSchema: mcpSchema({
|
|
4227
|
+
requirements: {
|
|
4228
|
+
type: "array", description: "Reconstructed requirements (at most 100)",
|
|
4229
|
+
items: {
|
|
4230
|
+
type: "object",
|
|
4231
|
+
properties: {
|
|
4232
|
+
key: mcpStr("Semantic key, e.g. keys.search"), title: mcpStr("Title"), description: mcpStr("Description"),
|
|
4233
|
+
acceptanceCriteria: mcpStr("Given/When/Then scenario(s), newline-separated"), negativeCriteria: mcpStr("Negative scenario(s)"),
|
|
4234
|
+
type: mcpStr("functional or non-functional", { enum: ["functional", "non-functional"] }), epicKey: mcpStr("Epic key"),
|
|
4235
|
+
files: mcpStrArray("Files where it is built, e.g. src/app/x.ts:40-88"), commits: mcpStrArray("Commits where it was built"),
|
|
4236
|
+
},
|
|
4237
|
+
required: ["key", "title", "acceptanceCriteria"],
|
|
4238
|
+
},
|
|
4239
|
+
},
|
|
4240
|
+
}, ["requirements"]),
|
|
4241
|
+
run: async (a) => mcpCall("uploadBaselineRequirements", { projectId: a.projectId, requirements: a.requirements }),
|
|
4242
|
+
},
|
|
4064
4243
|
{
|
|
4065
4244
|
name: "list_requirement_library",
|
|
4066
4245
|
description: "The account's requirement library (library.shared-requirements): requirements shared by all projects of the same owner, with key, title, category, type and version.",
|
|
@@ -4211,10 +4390,13 @@ Follow these steps in order:
|
|
|
4211
4390
|
- Only status=approved, functional requirements without a sprint are candidates. Non-functional (compliance) requirements are continuous — never plan them. Never touch completed sprints or the requirements in them. Requirements in other sprints stay where they are, except carry-over from overdue sprints (below).
|
|
4212
4391
|
- An epic's requirements never go into an earlier sprint than the requirements of the epics it dependsOn.
|
|
4213
4392
|
- Order by priority (1 first), then epic priority.
|
|
4214
|
-
- Per sprint, plan
|
|
4393
|
+
- Per sprint, plan up to sprint_velocity's capacity (points, or requirements when no completed sprint has points — say so), counting what is already planned there (openSprints[].points). If there is no history, say so and propose a conservative number. Mention averageCompletionRate (the share of planned requirements that usually gets done) in the proposal.
|
|
4394
|
+
- User demand (signals.user-feature-requests): requirements carry requestVotes, the votes of the users' requests linked to them. Among requirements of the same priority, plan the ones with more votes first, and name the votes in the reason when they decided the order.
|
|
4395
|
+
- Points (sprint.requirement-points): a requirement without points gets proposed points, 1, 2, 3, 5 or 8 — anything bigger should be split, say so instead. Pass them as points on the propose_sprint_plan row; approving the row sets them. Non-functional requirements have no points.
|
|
4215
4396
|
- Carry-over: a sprint is overdue when its end date (releaseDate) is before today and it is not completed. Requirements in an overdue sprint that are approved or in progress are candidates to MOVE to an open sprint; they keep their status and assignee, and the reason names the overdue sprint. Never move requirements out of a sprint that has not passed its end date.
|
|
4216
4397
|
- If the requirements don't fit in the existing sprints, propose new sprints (name + end date) — don't create them yet.
|
|
4217
|
-
|
|
4398
|
+
- Mid-release change (sprint.mid-release-swap): when the user wants something taken into a sprint that is in progress (start date passed, end date not), don't overfill it silently — propose a swap (propose_sprint_plan swaps): the requirement in, and not-started (approved) requirements of about the same points out to the next open sprint, lowest priority first, never one a staying requirement depends on through its epic. Show it as its own table: sprint | in | out | points freed | reason.
|
|
4399
|
+
3. Present the proposal as a table: sprint | requirement key | title | points (mark proposed ones) | reason (priority / epic dependency / capacity) | Claude verifies by (how you will verify it yourself — unit/integration tests, an API call, a build check — or "manual tests only" when you can't). Pass the same text as selfVerification on each propose_sprint_plan row, and manualOnly true for the "manual tests only" ones (the protocol must then have a test for them). Show moves out of overdue sprints as their own rows, marked as moves, separate from newly planned requirements. Also list what you deliberately left out and why, and any dependency conflicts you found.
|
|
4218
4400
|
4. STOP and ask the user: approve here, or save it as a proposal to decide later in qa-tools? Change nothing before that. Apply any adjustments the user asks for and show the table again.
|
|
4219
4401
|
- If nobody is there to answer (an unattended run), or the user chooses "later": call propose_sprint_plan with the same rows, and report the result. Do not apply anything yourself.
|
|
4220
4402
|
5. After approval in this conversation: create_sprint for any new sprints, then update_requirement with sprintId for each planned requirement. Report each change and any refusal verbatim — never retry a refused change in a different way.
|
|
@@ -4273,7 +4455,7 @@ async function mcpHandle(msg, defaultProjectId) {
|
|
|
4273
4455
|
if (!args.projectId) throw new McpToolError("No project configured. Pass projectId, or run: qatools setup");
|
|
4274
4456
|
}
|
|
4275
4457
|
const data = await tool.run(args);
|
|
4276
|
-
return { content: [{ type: "text", text: JSON.stringify(data ?? null, null, 2) }] };
|
|
4458
|
+
return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data ?? null, null, 2) }] };
|
|
4277
4459
|
} catch (e) {
|
|
4278
4460
|
// Tool failures (refusals, backend permission errors) go back as tool results the model can read.
|
|
4279
4461
|
return { content: [{ type: "text", text: e.message || String(e) }], isError: true };
|