qatools-cli 1.2.5 → 1.2.7
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/package.json +1 -1
- package/qatools.js +60 -14
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "qatools-cli",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.7",
|
|
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
|
@@ -135,6 +135,24 @@ async function authenticate(options) {
|
|
|
135
135
|
const BACKLOG_PREFIX = { bug: "AVV", improvement: "IMP", requirement_gap: "GAP", technical_defect: "DEF" };
|
|
136
136
|
const backlogLabel = (type, n) => `${BACKLOG_PREFIX[type] || "AVV"}-${n}`;
|
|
137
137
|
|
|
138
|
+
// Images as evidence (testing.evidence-attachments): upload local image files through the backend and
|
|
139
|
+
// return their storage paths, to pass as `attachments` with the evidence. Shared by CLI and MCP.
|
|
140
|
+
const EVIDENCE_EXT = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" };
|
|
141
|
+
async function uploadEvidenceFiles(projectId, files) {
|
|
142
|
+
const paths = [];
|
|
143
|
+
for (const f of files || []) {
|
|
144
|
+
const abs = path.resolve(String(f));
|
|
145
|
+
const contentType = EVIDENCE_EXT[path.extname(abs).toLowerCase()];
|
|
146
|
+
if (!contentType) throw new Error(`${f}: only .png, .jpg, .webp or .gif can be attached`);
|
|
147
|
+
if (!fs.existsSync(abs)) throw new Error(`${f}: file not found`);
|
|
148
|
+
const buf = fs.readFileSync(abs);
|
|
149
|
+
if (buf.length > 4 * 1024 * 1024) throw new Error(`${f}: larger than 4 MB`);
|
|
150
|
+
const res = await httpsCallable(functions, "uploadEvidenceImage")({ projectId, contentType, dataBase64: buf.toString("base64"), filename: path.basename(abs) });
|
|
151
|
+
paths.push(res.data.path);
|
|
152
|
+
}
|
|
153
|
+
return paths;
|
|
154
|
+
}
|
|
155
|
+
|
|
138
156
|
// Status guards shared by the CLI commands and the MCP server (cli.mcp-access-parity) —
|
|
139
157
|
// one implementation, so an MCP tool can never be looser than its CLI counterpart.
|
|
140
158
|
const REQUIREMENT_STATUSES_REQUIRING_EVIDENCE = new Set(["implemented", "tested"]);
|
|
@@ -716,7 +734,7 @@ function gitChangesSince(date) {
|
|
|
716
734
|
|
|
717
735
|
program
|
|
718
736
|
.command("compliance-check")
|
|
719
|
-
.description("List the sprint's continuous
|
|
737
|
+
.description("List the sprint's continuous (non-functional) requirements, their verification status and the git changes since the sprint started (run in the repo)")
|
|
720
738
|
.option("--sprint <id>", "Sprint ID (default: the active sprint)")
|
|
721
739
|
.option("--json", "Output JSON (for Claude / CI)")
|
|
722
740
|
.option("--project <id>", "Target project ID (overrides default)")
|
|
@@ -732,7 +750,7 @@ program
|
|
|
732
750
|
const changes = gitChangesSince(res.sprint.startDate);
|
|
733
751
|
if (options.json) { console.log(JSON.stringify({ ...res, changes }, null, 2)); process.exit(0); }
|
|
734
752
|
const done = res.requirements.filter(r => r.verification).length;
|
|
735
|
-
console.log(`Sprint ${res.sprint.name} [${res.sprint.status}] ${res.sprint.startDate || "?"} → ${res.sprint.releaseDate || "?"}: ${done}/${res.requirements.length}
|
|
753
|
+
console.log(`Sprint ${res.sprint.name} [${res.sprint.status}] ${res.sprint.startDate || "?"} → ${res.sprint.releaseDate || "?"}: ${done}/${res.requirements.length} continuous requirement(s) verified\n`);
|
|
736
754
|
for (const r of res.requirements) {
|
|
737
755
|
const st = r.verification ? (r.verification.result === "passed" ? "✓ passed" : "✗ failed") : "… to verify";
|
|
738
756
|
console.log(` ${st.padEnd(13)} [${r.key}] ${r.title}`);
|
|
@@ -750,10 +768,11 @@ program
|
|
|
750
768
|
|
|
751
769
|
program
|
|
752
770
|
.command("compliance-record")
|
|
753
|
-
.description("Record a
|
|
754
|
-
.requiredOption("--key <requirementKey>", "
|
|
771
|
+
.description("Record a continuous requirement's verification for the sprint (evidence required). failed creates an AVV signal.")
|
|
772
|
+
.requiredOption("--key <requirementKey>", "Continuous requirement key")
|
|
755
773
|
.requiredOption("--result <result>", "passed or failed")
|
|
756
774
|
.requiredOption("--evidence <text>", "What was checked in the sprint's diff and what was found (file:line), min 10 chars")
|
|
775
|
+
.option("--attach <files...>", "Image file(s) as evidence (png/jpg/webp/gif, max 4 MB each)")
|
|
757
776
|
.option("--sprint <id>", "Sprint ID (default: the active sprint)")
|
|
758
777
|
.option("--commit <sha>", "Commit checked (default: git HEAD)")
|
|
759
778
|
.option("--project <id>", "Target project ID (overrides default)")
|
|
@@ -767,7 +786,8 @@ program
|
|
|
767
786
|
let commit = options.commit || "";
|
|
768
787
|
if (!commit) { try { commit = require("child_process").execSync("git rev-parse HEAD", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { /* not a repo */ } }
|
|
769
788
|
try {
|
|
770
|
-
const
|
|
789
|
+
const attachments = await uploadEvidenceFiles(projectId, options.attach);
|
|
790
|
+
const res = (await httpsCallable(functions, "recordSprintVerification")({ projectId, sprintId: options.sprint || null, requirementKey: options.key, result: options.result, evidence: options.evidence, commit, attachments })).data;
|
|
771
791
|
console.log(`Recorded ${res.requirementKey}: ${res.result} for sprint ${res.sprintName}${res.signal ? ` — signal ${res.signal}` : ""}.`);
|
|
772
792
|
} catch (e) {
|
|
773
793
|
console.error("Failed:", e.message);
|
|
@@ -1381,7 +1401,7 @@ program
|
|
|
1381
1401
|
const items = data.agenda.continuousUnverified.map(r => ` • [${r.key}] ${r.title}`);
|
|
1382
1402
|
sections.push({
|
|
1383
1403
|
icon: "🟢",
|
|
1384
|
-
title: `${data.agenda.continuousUnverified.length} continuous
|
|
1404
|
+
title: `${data.agenda.continuousUnverified.length} continuous requirement${data.agenda.continuousUnverified.length > 1 ? 's' : ''} need verification for "${data.agenda.continuousUnverified[0].sprintName}"`,
|
|
1385
1405
|
items,
|
|
1386
1406
|
next: `verify each against this sprint's diff and record result via UI Sprintar tab`,
|
|
1387
1407
|
});
|
|
@@ -1439,6 +1459,7 @@ program
|
|
|
1439
1459
|
.option("-i, --id <id>", "Single requirement ID to update")
|
|
1440
1460
|
.option("--status <status>", "New status (draft/approved/rejected/implemented/tested/superseded)")
|
|
1441
1461
|
.option("--evidence <text>", "REQUIRED when status=implemented or tested. Cite test output, file:line, expected vs actual, or 'no test applies because <reason>'.")
|
|
1462
|
+
.option("--attach <files...>", "Image file(s) as evidence (png/jpg/webp/gif, max 4 MB each)")
|
|
1442
1463
|
.option("--epic <key>", "Set epicKey")
|
|
1443
1464
|
.option("--sprint <id>", "Set sprintId (use empty string to clear)")
|
|
1444
1465
|
.option("--type <type>", "Set type (functional/non-functional)")
|
|
@@ -1508,6 +1529,10 @@ program
|
|
|
1508
1529
|
for (const [requirementId, fields] of Object.entries(updates)) {
|
|
1509
1530
|
try {
|
|
1510
1531
|
const payload = { projectId, requirementId, updates: fields };
|
|
1532
|
+
if (options.attach && requirementId === options.id) {
|
|
1533
|
+
if (!evidenceById[requirementId]) throw new Error("--attach needs --evidence (images belong to an evidence entry)");
|
|
1534
|
+
payload.attachments = await uploadEvidenceFiles(projectId, options.attach);
|
|
1535
|
+
}
|
|
1511
1536
|
if (evidenceById[requirementId]) payload.evidence = evidenceById[requirementId];
|
|
1512
1537
|
await updateReq(payload);
|
|
1513
1538
|
ok++;
|
|
@@ -1691,6 +1716,7 @@ program
|
|
|
1691
1716
|
.option("-i, --id <id>", "Single item ID to update")
|
|
1692
1717
|
.option("--status <status>", "New status")
|
|
1693
1718
|
.option("--evidence <text>", "REQUIRED when status=resolved (except for GAP). Cite the verification: test output, file:line, expected vs actual, or 'no test applies because <reason>'.")
|
|
1719
|
+
.option("--attach <files...>", "Image file(s) as evidence (png/jpg/webp/gif, max 4 MB each)")
|
|
1694
1720
|
.option("--comment <text>", "Add comment")
|
|
1695
1721
|
.option("--assigned <email>", "Assign to")
|
|
1696
1722
|
.option("--sprint <id>", "Set sprint ID")
|
|
@@ -1790,6 +1816,13 @@ program
|
|
|
1790
1816
|
}
|
|
1791
1817
|
}
|
|
1792
1818
|
|
|
1819
|
+
if (options.attach) {
|
|
1820
|
+
if (!options.id || !options.evidence) { console.error("--attach needs --id and --evidence"); process.exit(1); }
|
|
1821
|
+
const pid = options.project || getCredentials()?.projectId;
|
|
1822
|
+
if (!pid) { console.error("--attach needs a project: qatools setup, or --project <id>"); process.exit(1); }
|
|
1823
|
+
try { updates[options.id].attachments = await uploadEvidenceFiles(pid, options.attach); }
|
|
1824
|
+
catch (e) { console.error("Attachment upload failed:", e.message); process.exit(1); }
|
|
1825
|
+
}
|
|
1793
1826
|
const updateItems = httpsCallable(functions, "updateBacklogItems");
|
|
1794
1827
|
try {
|
|
1795
1828
|
const result = await updateItems({ updates });
|
|
@@ -2656,13 +2689,14 @@ If the qa-tools MCP server (\`qatools mcp\`) is available, use its tools and the
|
|
|
2656
2689
|
Capacity: count how many requirements reached implemented/tested in each completed sprint (MCP: \`sprint_velocity\`). If there is no history, say so and propose a conservative number.
|
|
2657
2690
|
|
|
2658
2691
|
2. Draft a proposal:
|
|
2659
|
-
- Only approved requirements without a sprint are candidates.
|
|
2692
|
+
- Only approved, functional requirements without a sprint are candidates. Continuous (non-functional) requirements are never planned — they are checked against every sprint.
|
|
2660
2693
|
- Never touch completed sprints or requirements in one — the backend refuses.
|
|
2661
2694
|
- An epic's requirements never go before the requirements of the epics it dependsOn.
|
|
2662
2695
|
- Priority 1 first, then epic priority.
|
|
2696
|
+
- Per sprint: roughly the capacity average, counting requirements already in the sprint.
|
|
2663
2697
|
- If existing sprints don't fit, propose new ones (name + end date) — don't create them yet.
|
|
2664
2698
|
|
|
2665
|
-
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. Change nothing until the user approves.
|
|
2699
|
+
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.
|
|
2666
2700
|
|
|
2667
2701
|
4. Apply after approval:
|
|
2668
2702
|
\`qatools sprint-create --name "Release 4.1" --end 2026-12-15\`
|
|
@@ -3560,8 +3594,9 @@ const mcpTools = [
|
|
|
3560
3594
|
sprintId: mcpStr("Sprint ID to plan it in"),
|
|
3561
3595
|
status: mcpStr("Initial status (default draft)", { enum: MCP_REQ_STATUSES }),
|
|
3562
3596
|
force: mcpBool("Skip the semantic similarity check"),
|
|
3597
|
+
version: mcpInt("New version of an existing key (e.g. 2). Then set the old version to superseded with update_requirement."),
|
|
3563
3598
|
}, ["key", "title"]),
|
|
3564
|
-
run: async (a) => mcpCall("createRequirement", { projectId: a.projectId, ...mcpPick(a, ["key", "title", "description", "acceptanceCriteria", "negativeCriteria", "type", "priority", "category", "epicKey", "sprintId", "status", "force"]) }),
|
|
3599
|
+
run: async (a) => mcpCall("createRequirement", { projectId: a.projectId, ...mcpPick(a, ["key", "title", "description", "acceptanceCriteria", "negativeCriteria", "type", "priority", "category", "epicKey", "sprintId", "status", "force", "version"]) }),
|
|
3565
3600
|
},
|
|
3566
3601
|
{
|
|
3567
3602
|
name: "update_requirement",
|
|
@@ -3576,6 +3611,7 @@ const mcpTools = [
|
|
|
3576
3611
|
title: mcpStr("Title"),
|
|
3577
3612
|
description: mcpStr("Description"),
|
|
3578
3613
|
acceptanceCriteria: mcpStr("Acceptance criteria"),
|
|
3614
|
+
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3579
3615
|
}, ["requirementId"]),
|
|
3580
3616
|
run: async (a) => {
|
|
3581
3617
|
const updates = mcpPick(a, ["status", "epicKey", "sprintId", "type", "title", "description", "acceptanceCriteria"]);
|
|
@@ -3586,6 +3622,10 @@ const mcpTools = [
|
|
|
3586
3622
|
}
|
|
3587
3623
|
const payload = { projectId: a.projectId, requirementId: a.requirementId, updates };
|
|
3588
3624
|
if (a.evidence) payload.evidence = a.evidence;
|
|
3625
|
+
if (a.attachments?.length) {
|
|
3626
|
+
if (!a.evidence) throw new McpToolError("attachments need evidence — images belong to an evidence entry");
|
|
3627
|
+
payload.attachments = await uploadEvidenceFiles(a.projectId, a.attachments);
|
|
3628
|
+
}
|
|
3589
3629
|
await mcpCall("updateRequirement", payload);
|
|
3590
3630
|
return { updated: a.requirementId, fields: Object.keys(updates) };
|
|
3591
3631
|
},
|
|
@@ -3719,21 +3759,22 @@ const mcpTools = [
|
|
|
3719
3759
|
},
|
|
3720
3760
|
{
|
|
3721
3761
|
name: "list_compliance_due",
|
|
3722
|
-
description: "The sprint's continuous
|
|
3762
|
+
description: "The sprint's continuous requirements (non-functional, active epic) with their verification status for the sprint, including acceptance criteria / verification method. Check each against the sprint's diff (git log --since <startDate> in the repo), then record_compliance_verification.",
|
|
3723
3763
|
inputSchema: mcpSchema({ sprintId: mcpStr("Sprint ID (default: the active sprint)") }),
|
|
3724
3764
|
run: async (a) => mcpCall("listComplianceDue", { projectId: a.projectId, sprintId: a.sprintId || null }),
|
|
3725
3765
|
},
|
|
3726
3766
|
{
|
|
3727
3767
|
name: "record_compliance_verification",
|
|
3728
|
-
description: "Record the result of checking a
|
|
3768
|
+
description: "Record the result of checking a continuous requirement against the sprint's diff. Evidence is required (what was checked, file:line). failed creates an AVV signal (deduplicated). Not available to propose-only keys.",
|
|
3729
3769
|
inputSchema: mcpSchema({
|
|
3730
|
-
requirementKey: mcpStr("
|
|
3770
|
+
requirementKey: mcpStr("Continuous requirement key"),
|
|
3731
3771
|
result: mcpStr("passed or failed", { enum: ["passed", "failed"] }),
|
|
3732
3772
|
evidence: mcpStr("What was checked in the sprint's diff and what was found (file:line), min 10 chars"),
|
|
3733
3773
|
sprintId: mcpStr("Sprint ID (default: the active sprint)"),
|
|
3734
3774
|
commit: mcpStr("Commit checked"),
|
|
3775
|
+
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3735
3776
|
}, ["requirementKey", "result", "evidence"]),
|
|
3736
|
-
run: async (a) => mcpCall("recordSprintVerification", { projectId: a.projectId, ...mcpPick(a, ["requirementKey", "result", "evidence", "sprintId", "commit"]) }),
|
|
3777
|
+
run: async (a) => mcpCall("recordSprintVerification", { projectId: a.projectId, ...mcpPick(a, ["requirementKey", "result", "evidence", "sprintId", "commit"]), attachments: await uploadEvidenceFiles(a.projectId, a.attachments) }),
|
|
3737
3778
|
},
|
|
3738
3779
|
{
|
|
3739
3780
|
name: "notify_owner",
|
|
@@ -3824,6 +3865,7 @@ const mcpTools = [
|
|
|
3824
3865
|
description: mcpStr("New description"),
|
|
3825
3866
|
mailNotify: mcpBool("Item email notifications on/off"),
|
|
3826
3867
|
skipTestVerification: mcpBool("Allow resolved without ready_for_test — only when no test applies. Evidence is still required."),
|
|
3868
|
+
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3827
3869
|
}, ["itemId"]),
|
|
3828
3870
|
run: async (a) => {
|
|
3829
3871
|
const u = mcpPick(a, ["status", "evidence", "assignedTo", "developer", "sprintId", "priority", "requirementKey", "description", "mailNotify"]);
|
|
@@ -3842,6 +3884,10 @@ const mcpTools = [
|
|
|
3842
3884
|
if (v.evidence.length) throw new McpToolError("Refusing status=resolved without evidence (min 10 chars). Cite the verification, or set ready_for_test instead.");
|
|
3843
3885
|
if (v.flow.length) throw new McpToolError(`Refusing status=resolved: item is '${v.flow[0].currentStatus}', not ready_for_test. Backlog flow: open → in_progress → ready_for_test → resolved. Set ready_for_test and let a tester verify, or pass skipTestVerification if no test applies.`);
|
|
3844
3886
|
}
|
|
3887
|
+
if (a.attachments?.length) {
|
|
3888
|
+
if (!a.evidence) throw new McpToolError("attachments need evidence — images belong to an evidence entry");
|
|
3889
|
+
u.attachments = await uploadEvidenceFiles(a.projectId, a.attachments);
|
|
3890
|
+
}
|
|
3845
3891
|
const r = await mcpCall("updateBacklogItems", { updates });
|
|
3846
3892
|
// The backend skips items it can't find or the caller can't access, instead of throwing.
|
|
3847
3893
|
if (!r.updatedCount) throw new McpToolError(`Item ${a.itemId} was not updated — it does not exist or this login has no access to its project.`);
|
|
@@ -3896,7 +3942,7 @@ Work through these steps, then stop:
|
|
|
3896
3942
|
1. get_agenda. This is your task list.
|
|
3897
3943
|
2. Sessions awaiting analysis: for each, read_session and compare every FEL result against its requirement (list_requirements). Upload your analysis with upload_analysis — backlogUpdates may only contain comments. For a real deviation not already on the backlog (check list_backlog by requirementKey), create_backlog_item with type bug (AVV), requirement_gap (GAP) or technical_defect (DEF) and the requirementKey. Cite the test and expected vs actual; never speculate.
|
|
3898
3944
|
3. Planning: list_plan_proposals with status pending. If one created by Claude is already pending, do NOT create another — mention it in the summary. Otherwise, if there are approved functional requirements without a sprint and sprints that are not completed, follow the plan_sprints procedure (sprint_velocity, epic dependsOn, priority) and save the result with propose_sprint_plan.
|
|
3899
|
-
4. Approved requirements without tests (from the agenda) and
|
|
3945
|
+
4. Approved requirements without tests (from the agenda) and continuous requirements still unverified this sprint (list_compliance_due): do not act — a propose-only key can't record verifications — just count them and name the unverified continuous requirement keys in the summary.
|
|
3900
3946
|
5. Finish with notify_owner. Subject: "qa-tools daily run: <project> — <n> to review". Body, plain text, short:
|
|
3901
3947
|
- what you analysed and which signals you created (labels),
|
|
3902
3948
|
- the plan proposal you saved (or why none),
|