qatools-cli 1.2.19 → 1.2.21
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 +69 -22
- package/package.json +1 -1
- package/qatools.js +71 -3
package/context-sync.js
CHANGED
|
@@ -55,7 +55,7 @@ function renderToolsSection() {
|
|
|
55
55
|
return [
|
|
56
56
|
"### qa-tools tools for this project",
|
|
57
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
|
-
"-
|
|
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
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
60
|
"",
|
|
61
61
|
].join("\n");
|
|
@@ -68,28 +68,44 @@ function requestsIntegrationPrompt(projectName) {
|
|
|
68
68
|
return [
|
|
69
69
|
`# Connect this app's feature requests to qa-tools${projectName ? ` (project "${projectName}")` : ""}`,
|
|
70
70
|
"",
|
|
71
|
-
"
|
|
72
|
-
"
|
|
73
|
-
"
|
|
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.",
|
|
74
79
|
"",
|
|
75
80
|
"## Procedure",
|
|
76
|
-
"1. Find where the app keeps requests and votes (collection/table, fields
|
|
77
|
-
" shows them. Read the code. If
|
|
78
|
-
"
|
|
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`.",
|
|
79
85
|
"2. Ask the user for the feature-request key. The project owner creates it in qa-tools: Members → Requests from the",
|
|
80
|
-
" app → Create key. It starts with `fr-`, is shown once, and can only send
|
|
81
|
-
" Keep it server-side as a secret named QATOOLS_FEATURE_REQUEST_KEY. Never in client code, never in the repo
|
|
82
|
-
"
|
|
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:",
|
|
83
94
|
" - sends every request with its current votes: action \"upsert\", at most 200 per call. The app's own id",
|
|
84
95
|
" identifies a request, so sending all of them every time is fine — it updates, it does not duplicate;",
|
|
85
96
|
" - reads the status of the same ids: action \"status\", at most 500 per call;",
|
|
86
97
|
" - stores each status on the app's own request record (e.g. a field qaStatus).",
|
|
87
|
-
"
|
|
88
|
-
"
|
|
89
|
-
"
|
|
90
|
-
"
|
|
91
|
-
"
|
|
92
|
-
"
|
|
98
|
+
" To show the team's replies (and let users comment), read them with action comments and send users' comments with",
|
|
99
|
+
" action comment — both take the app's own request id, also for synced requests.",
|
|
100
|
+
"4. Show the status on the request page, in the app's language, with the votes: new → received; accepted → accepted",
|
|
101
|
+
" (it is linked to a requirement); planned → the release name and its planned date (releaseDate); released →",
|
|
102
|
+
" released; declined → declined with the reason (members write it for the users).",
|
|
103
|
+
"5. Verify it yourself before you say it works: (A) run the job once, or (B) create a request and vote through your",
|
|
104
|
+
" own routes; then `qatools feature-requests` must list the requests with their votes, and the app must show",
|
|
105
|
+
" status \"new\". Then link one request to a requirement in a sprint yourself: `qatools feature-request-link --id",
|
|
106
|
+
" <app id> --requirement <key>`; after that (and the next sync for A) the app must show \"planned\" with the release",
|
|
107
|
+
" and date. Unless the link is right, undo it: `qatools feature-request-unlink --id <app id>`. Report what you saw.",
|
|
108
|
+
" Declining (`qatools feature-request-decline --id <id> --reason \"…\"`) is a member's decision — never do it yourself.",
|
|
93
109
|
"6. If the app's requirements in qa-tools do not cover the request page or this sync, say so — the user decides",
|
|
94
110
|
" whether to add requirements.",
|
|
95
111
|
"",
|
|
@@ -101,15 +117,46 @@ function requestsIntegrationPrompt(projectName) {
|
|
|
101
117
|
' { "action": "upsert", "requests": [ { "id": "42", "title": "Dark mode", "description": "…", "votes": 15, "url": "https://…" } ] }',
|
|
102
118
|
' → { "created": 1, "updated": 0, "refused": [] } (refused: [{ "id": "", "reason": "id and title are required" }])',
|
|
103
119
|
"",
|
|
104
|
-
"Read status:",
|
|
120
|
+
"Read status (A):",
|
|
105
121
|
' { "action": "status", "ids": ["42", "43"] }',
|
|
106
|
-
' → { "statuses": [ { "id": "42", "status": "planned", "sprint": "Release 4.1", "releaseDate": "2026-11-18" },',
|
|
107
|
-
' { "id": "43", "status": "declined", "reason": "…" } ] }',
|
|
108
|
-
" status is one of: new, planned, released, declined, unknown (never sent)",
|
|
122
|
+
' → { "statuses": [ { "id": "42", "votes": 15, "status": "planned", "sprint": "Release 4.1", "releaseDate": "2026-11-18" },',
|
|
123
|
+
' { "id": "43", "votes": 2, "status": "declined", "reason": "…" } ] }',
|
|
124
|
+
" status is one of: new, accepted, planned, released, declined, unknown (never sent)",
|
|
125
|
+
"",
|
|
126
|
+
"Kept by qa-tools (B) — userId is the app's id for the user who acts; qa-tools stores only a hash of it:",
|
|
127
|
+
' { "action": "list", "userId": "u2" }',
|
|
128
|
+
' → { "requests": [ { "id": "qa-…", "title": "…", "description": "…", "votes": 3, "comments": 1, "voted": true,',
|
|
129
|
+
' "status": "planned", "sprint": "Release 4.1", "releaseDate": "2026-11-18" } ] } (most votes first)',
|
|
130
|
+
' { "action": "create", "userId": "u1", "title": "Dark mode", "description": "…" } → { "request": { …, "votes": 1, "voted": true } }',
|
|
131
|
+
' { "action": "vote", "userId": "u2", "id": "qa-…" } → { "id": "qa-…", "votes": 2, "voted": true }',
|
|
132
|
+
' { "action": "vote", "userId": "u2", "id": "qa-…", "vote": false } → takes the vote back; one vote per user and request',
|
|
133
|
+
' { "action": "comment", "userId": "u2", "userName": "Anna", "id": "qa-…", "text": "…" }',
|
|
134
|
+
' { "action": "comments", "id": "qa-…" } → { "comments": [ { "author": "Anna", "team": false, "text": "…", "at": "…" },',
|
|
135
|
+
' { "author": "team", "team": true, "text": "…", "at": "…" } ] }',
|
|
136
|
+
" Replies from the project's members come back with author \"team\". comment and comments also work for requests the",
|
|
137
|
+
" app syncs itself (A), with the app's own id. Votes on synced requests are refused (409) — their votes come from the app.",
|
|
138
|
+
"",
|
|
139
|
+
"Errors: 401 missing key, 403 wrong or revoked key, 400 bad body (e.g. no userId, no title, title over 300",
|
|
140
|
+
"characters), 404 unknown request, 409 vote on a synced request, 429 more than 600 calls a minute from one server.",
|
|
109
141
|
"",
|
|
110
|
-
"
|
|
142
|
+
"## Example B (Node/Express routes in the app's server — adapt to the app's framework and auth)",
|
|
143
|
+
FENCE + "js",
|
|
144
|
+
`const QA = "${FEATURE_REQUESTS_URL}";`,
|
|
145
|
+
"const qa = async (body) => {",
|
|
146
|
+
' const res = await fetch(QA, { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + process.env.QATOOLS_FEATURE_REQUEST_KEY }, body: JSON.stringify(body) });',
|
|
147
|
+
" const json = await res.json();",
|
|
148
|
+
' if (!res.ok) throw Object.assign(new Error(json.error), { status: res.status });',
|
|
149
|
+
" return json;",
|
|
150
|
+
"};",
|
|
151
|
+
"// req.user is the app's logged-in user",
|
|
152
|
+
'app.get("/api/requests", async (req, res) => res.json(await qa({ action: "list", userId: req.user.id })));',
|
|
153
|
+
'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 })));',
|
|
154
|
+
'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 })));',
|
|
155
|
+
'app.get("/api/requests/:id/comments", async (req, res) => res.json(await qa({ action: "comments", id: req.params.id })));',
|
|
156
|
+
'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 })));',
|
|
157
|
+
FENCE,
|
|
111
158
|
"",
|
|
112
|
-
"## Example (Node, Firebase scheduled function — adapt names to the app)",
|
|
159
|
+
"## Example A (Node, Firebase scheduled function — adapt names to the app)",
|
|
113
160
|
FENCE + "js",
|
|
114
161
|
'const { onSchedule } = require("firebase-functions/v2/scheduler");',
|
|
115
162
|
'const { defineSecret } = require("firebase-functions/params");',
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "qatools-cli",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.21",
|
|
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
|
@@ -905,7 +905,8 @@ program
|
|
|
905
905
|
if (!requests.length) { console.log("No requests from users yet. Connect the app: qatools requests-integration-prompt"); process.exit(0); }
|
|
906
906
|
console.log(`${requests.length} request(s):\n`);
|
|
907
907
|
for (const r of requests) {
|
|
908
|
-
|
|
908
|
+
const where = r.status === "planned" ? ` → ${r.sprint} (${r.releaseDate})` : r.status === "declined" && r.reason ? ` — "${r.reason}"` : "";
|
|
909
|
+
console.log(` ▲ ${String(r.votes || 0).padStart(4)} ${r.status.padEnd(8)} ${r.title} (id ${r.externalId}${r.requirementKey ? `, requirement ${r.requirementKey}` : ""})${where}`);
|
|
909
910
|
}
|
|
910
911
|
process.exit(0);
|
|
911
912
|
} catch (e) {
|
|
@@ -914,6 +915,61 @@ program
|
|
|
914
915
|
}
|
|
915
916
|
});
|
|
916
917
|
|
|
918
|
+
// signals.feature-requests-cli: act on a request from the terminal — a request by the app's id, a requirement by its key
|
|
919
|
+
async function decideRequestFromCli(options, action, extra) {
|
|
920
|
+
await authenticate(options);
|
|
921
|
+
const projectId = options.project || getCredentials()?.projectId;
|
|
922
|
+
if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
|
|
923
|
+
try {
|
|
924
|
+
const { data } = await httpsCallable(functions, "decideFeatureRequest")({ projectId, externalId: String(options.id), action, ...extra });
|
|
925
|
+
return data;
|
|
926
|
+
} catch (e) {
|
|
927
|
+
console.error(e.message);
|
|
928
|
+
process.exit(1);
|
|
929
|
+
}
|
|
930
|
+
}
|
|
931
|
+
|
|
932
|
+
program
|
|
933
|
+
.command("feature-request-link")
|
|
934
|
+
.description("Link a request from the app's users to a requirement; the app then shows it as accepted, or planned when the requirement is in a sprint")
|
|
935
|
+
.requiredOption("--id <id>", "The request's id in the app")
|
|
936
|
+
.requiredOption("--requirement <key>", "Requirement key, e.g. reports.export")
|
|
937
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
938
|
+
.option("-e, --email <email>", "Login email")
|
|
939
|
+
.option("-p, --password <password>", "Login password")
|
|
940
|
+
.action(async (options) => {
|
|
941
|
+
await decideRequestFromCli(options, "link", { requirementKey: options.requirement });
|
|
942
|
+
console.log(`✓ Request ${options.id} linked to ${options.requirement}. Its status for the app: qatools feature-requests`);
|
|
943
|
+
process.exit(0);
|
|
944
|
+
});
|
|
945
|
+
|
|
946
|
+
program
|
|
947
|
+
.command("feature-request-unlink")
|
|
948
|
+
.description("Undo a link: the request is no longer linked to a requirement")
|
|
949
|
+
.requiredOption("--id <id>", "The request's id in the app")
|
|
950
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
951
|
+
.option("-e, --email <email>", "Login email")
|
|
952
|
+
.option("-p, --password <password>", "Login password")
|
|
953
|
+
.action(async (options) => {
|
|
954
|
+
const res = await decideRequestFromCli(options, "unlink", {});
|
|
955
|
+
console.log(`✓ Request ${options.id} unlinked (status: ${res.state}).`);
|
|
956
|
+
process.exit(0);
|
|
957
|
+
});
|
|
958
|
+
|
|
959
|
+
program
|
|
960
|
+
.command("feature-request-decline")
|
|
961
|
+
.description("Decline a request with a reason the app shows to its users. A member's decision: refused for Claude's API key.")
|
|
962
|
+
.requiredOption("--id <id>", "The request's id in the app")
|
|
963
|
+
.requiredOption("--reason <text>", "Why — shown to the app's users")
|
|
964
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
965
|
+
.option("-e, --email <email>", "Login email")
|
|
966
|
+
.option("-p, --password <password>", "Login password")
|
|
967
|
+
.action(async (options) => {
|
|
968
|
+
await decideRequestFromCli(options, "decline", { reason: options.reason });
|
|
969
|
+
console.log(`✓ Request ${options.id} declined.`);
|
|
970
|
+
process.exit(0);
|
|
971
|
+
});
|
|
972
|
+
|
|
917
973
|
// requirements.baseline-from-code: reconstruct requirements for what is already built
|
|
918
974
|
program
|
|
919
975
|
.command("baseline-prompt")
|
|
@@ -2761,7 +2817,7 @@ App Context → Epics → Requirements → Sprint → Implementation → Test
|
|
|
2761
2817
|
|
|
2762
2818
|
## Tools you may not think of
|
|
2763
2819
|
- 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
|
-
-
|
|
2820
|
+
- 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
2821
|
- Something more important must go into a sprint in progress: propose a swap instead of overfilling it; a member approves.
|
|
2766
2822
|
`,
|
|
2767
2823
|
|
|
@@ -4204,10 +4260,22 @@ const mcpTools = [
|
|
|
4204
4260
|
},
|
|
4205
4261
|
{
|
|
4206
4262
|
name: "list_feature_requests",
|
|
4207
|
-
description: "Requests from the app's users (signals.user-feature-requests), most votes first: title, votes,
|
|
4263
|
+
description: "Requests from the app's users (signals.user-feature-requests), most votes first: title, votes, status as the app sees it (new / accepted / planned / released / declined), requirementKey, sprint and releaseDate. Link or unlink with link_feature_request / unlink_feature_request; declining is a member's decision (web app or CLI with a member login).",
|
|
4208
4264
|
inputSchema: mcpSchema(),
|
|
4209
4265
|
run: async (a) => (await mcpCall("listFeatureRequests", { projectId: a.projectId })).requests,
|
|
4210
4266
|
},
|
|
4267
|
+
{
|
|
4268
|
+
name: "link_feature_request",
|
|
4269
|
+
description: "Link a request from the app's users to a requirement (signals.feature-requests-cli). The app then shows it as accepted, or planned with the release and date when the requirement is in a sprint — so link only where the requirement really covers the request.",
|
|
4270
|
+
inputSchema: mcpSchema({ id: mcpStr("The request's id in the app (externalId)"), requirementKey: mcpStr("Requirement key, e.g. reports.export") }, ["id", "requirementKey"]),
|
|
4271
|
+
run: async (a) => mcpCall("decideFeatureRequest", { projectId: a.projectId, externalId: a.id, action: "link", requirementKey: a.requirementKey }),
|
|
4272
|
+
},
|
|
4273
|
+
{
|
|
4274
|
+
name: "unlink_feature_request",
|
|
4275
|
+
description: "Undo a link between a request from the app's users and a requirement.",
|
|
4276
|
+
inputSchema: mcpSchema({ id: mcpStr("The request's id in the app (externalId)") }, ["id"]),
|
|
4277
|
+
run: async (a) => mcpCall("decideFeatureRequest", { projectId: a.projectId, externalId: a.id, action: "unlink" }),
|
|
4278
|
+
},
|
|
4211
4279
|
{
|
|
4212
4280
|
name: "requests_integration_prompt",
|
|
4213
4281
|
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.",
|