qatools-cli 1.2.4 → 1.2.6
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 +139 -3
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "qatools-cli",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.6",
|
|
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"]);
|
|
@@ -703,6 +721,81 @@ program
|
|
|
703
721
|
}
|
|
704
722
|
});
|
|
705
723
|
|
|
724
|
+
// ─── Compliance per sprint (compliance.sprint-verification-via-cli) ─────────
|
|
725
|
+
|
|
726
|
+
// Commits and changed files since a date, from the git repo in the current directory ("" if none).
|
|
727
|
+
function gitChangesSince(date) {
|
|
728
|
+
if (!date) return { commits: [], files: [] };
|
|
729
|
+
const git = (args) => { try { return require("child_process").execSync(`git ${args}`, { stdio: ["ignore", "pipe", "ignore"], maxBuffer: 32 * 1024 * 1024 }).toString(); } catch { return ""; } };
|
|
730
|
+
const commits = git(`log --since=${date} --pretty=format:%h%x09%s`).split("\n").filter(Boolean);
|
|
731
|
+
const files = [...new Set(git(`log --since=${date} --name-only --pretty=format:`).split("\n").map(s => s.trim()).filter(Boolean))].sort();
|
|
732
|
+
return { commits, files };
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
program
|
|
736
|
+
.command("compliance-check")
|
|
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)")
|
|
738
|
+
.option("--sprint <id>", "Sprint ID (default: the active sprint)")
|
|
739
|
+
.option("--json", "Output JSON (for Claude / CI)")
|
|
740
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
741
|
+
.option("-e, --email <email>", "Login email")
|
|
742
|
+
.option("-p, --password <password>", "Login password")
|
|
743
|
+
.action(async (options) => {
|
|
744
|
+
await authenticate(options);
|
|
745
|
+
const creds = getCredentials();
|
|
746
|
+
const projectId = options.project || creds?.projectId;
|
|
747
|
+
if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
|
|
748
|
+
try {
|
|
749
|
+
const res = (await httpsCallable(functions, "listComplianceDue")({ projectId, sprintId: options.sprint || null })).data;
|
|
750
|
+
const changes = gitChangesSince(res.sprint.startDate);
|
|
751
|
+
if (options.json) { console.log(JSON.stringify({ ...res, changes }, null, 2)); process.exit(0); }
|
|
752
|
+
const done = res.requirements.filter(r => r.verification).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`);
|
|
754
|
+
for (const r of res.requirements) {
|
|
755
|
+
const st = r.verification ? (r.verification.result === "passed" ? "✓ passed" : "✗ failed") : "… to verify";
|
|
756
|
+
console.log(` ${st.padEnd(13)} [${r.key}] ${r.title}`);
|
|
757
|
+
}
|
|
758
|
+
console.log(`\nChanges since ${res.sprint.startDate || "(no start date)"}: ${changes.commits.length} commit(s), ${changes.files.length} file(s)${changes.files.length ? "" : " — run inside the repo to see them"}.`);
|
|
759
|
+
for (const f of changes.files.slice(0, 40)) console.log(` ${f}`);
|
|
760
|
+
if (changes.files.length > 40) console.log(` … (+${changes.files.length - 40}, use --json for all)`);
|
|
761
|
+
console.log(`\nRecord each result: qatools compliance-record --key <key> --result passed|failed --evidence "<what you checked, file:line>"`);
|
|
762
|
+
} catch (e) {
|
|
763
|
+
console.error("Failed:", e.message);
|
|
764
|
+
process.exit(1);
|
|
765
|
+
}
|
|
766
|
+
process.exit(0);
|
|
767
|
+
});
|
|
768
|
+
|
|
769
|
+
program
|
|
770
|
+
.command("compliance-record")
|
|
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")
|
|
773
|
+
.requiredOption("--result <result>", "passed or failed")
|
|
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)")
|
|
776
|
+
.option("--sprint <id>", "Sprint ID (default: the active sprint)")
|
|
777
|
+
.option("--commit <sha>", "Commit checked (default: git HEAD)")
|
|
778
|
+
.option("--project <id>", "Target project ID (overrides default)")
|
|
779
|
+
.option("-e, --email <email>", "Login email")
|
|
780
|
+
.option("-p, --password <password>", "Login password")
|
|
781
|
+
.action(async (options) => {
|
|
782
|
+
await authenticate(options);
|
|
783
|
+
const creds = getCredentials();
|
|
784
|
+
const projectId = options.project || creds?.projectId;
|
|
785
|
+
if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
|
|
786
|
+
let commit = options.commit || "";
|
|
787
|
+
if (!commit) { try { commit = require("child_process").execSync("git rev-parse HEAD", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { /* not a repo */ } }
|
|
788
|
+
try {
|
|
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;
|
|
791
|
+
console.log(`Recorded ${res.requirementKey}: ${res.result} for sprint ${res.sprintName}${res.signal ? ` — signal ${res.signal}` : ""}.`);
|
|
792
|
+
} catch (e) {
|
|
793
|
+
console.error("Failed:", e.message);
|
|
794
|
+
process.exit(1);
|
|
795
|
+
}
|
|
796
|
+
process.exit(0);
|
|
797
|
+
});
|
|
798
|
+
|
|
706
799
|
program
|
|
707
800
|
.command("agenda-run-prompt")
|
|
708
801
|
.description("Print the unattended daily-agenda-run instructions, for: claude -p \"$(qatools agenda-run-prompt)\"")
|
|
@@ -1308,7 +1401,7 @@ program
|
|
|
1308
1401
|
const items = data.agenda.continuousUnverified.map(r => ` • [${r.key}] ${r.title}`);
|
|
1309
1402
|
sections.push({
|
|
1310
1403
|
icon: "🟢",
|
|
1311
|
-
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}"`,
|
|
1312
1405
|
items,
|
|
1313
1406
|
next: `verify each against this sprint's diff and record result via UI Sprintar tab`,
|
|
1314
1407
|
});
|
|
@@ -1366,6 +1459,7 @@ program
|
|
|
1366
1459
|
.option("-i, --id <id>", "Single requirement ID to update")
|
|
1367
1460
|
.option("--status <status>", "New status (draft/approved/rejected/implemented/tested/superseded)")
|
|
1368
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)")
|
|
1369
1463
|
.option("--epic <key>", "Set epicKey")
|
|
1370
1464
|
.option("--sprint <id>", "Set sprintId (use empty string to clear)")
|
|
1371
1465
|
.option("--type <type>", "Set type (functional/non-functional)")
|
|
@@ -1435,6 +1529,10 @@ program
|
|
|
1435
1529
|
for (const [requirementId, fields] of Object.entries(updates)) {
|
|
1436
1530
|
try {
|
|
1437
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
|
+
}
|
|
1438
1536
|
if (evidenceById[requirementId]) payload.evidence = evidenceById[requirementId];
|
|
1439
1537
|
await updateReq(payload);
|
|
1440
1538
|
ok++;
|
|
@@ -1618,6 +1716,7 @@ program
|
|
|
1618
1716
|
.option("-i, --id <id>", "Single item ID to update")
|
|
1619
1717
|
.option("--status <status>", "New status")
|
|
1620
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)")
|
|
1621
1720
|
.option("--comment <text>", "Add comment")
|
|
1622
1721
|
.option("--assigned <email>", "Assign to")
|
|
1623
1722
|
.option("--sprint <id>", "Set sprint ID")
|
|
@@ -1717,6 +1816,13 @@ program
|
|
|
1717
1816
|
}
|
|
1718
1817
|
}
|
|
1719
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
|
+
}
|
|
1720
1826
|
const updateItems = httpsCallable(functions, "updateBacklogItems");
|
|
1721
1827
|
try {
|
|
1722
1828
|
const result = await updateItems({ updates });
|
|
@@ -3487,8 +3593,9 @@ const mcpTools = [
|
|
|
3487
3593
|
sprintId: mcpStr("Sprint ID to plan it in"),
|
|
3488
3594
|
status: mcpStr("Initial status (default draft)", { enum: MCP_REQ_STATUSES }),
|
|
3489
3595
|
force: mcpBool("Skip the semantic similarity check"),
|
|
3596
|
+
version: mcpInt("New version of an existing key (e.g. 2). Then set the old version to superseded with update_requirement."),
|
|
3490
3597
|
}, ["key", "title"]),
|
|
3491
|
-
run: async (a) => mcpCall("createRequirement", { projectId: a.projectId, ...mcpPick(a, ["key", "title", "description", "acceptanceCriteria", "negativeCriteria", "type", "priority", "category", "epicKey", "sprintId", "status", "force"]) }),
|
|
3598
|
+
run: async (a) => mcpCall("createRequirement", { projectId: a.projectId, ...mcpPick(a, ["key", "title", "description", "acceptanceCriteria", "negativeCriteria", "type", "priority", "category", "epicKey", "sprintId", "status", "force", "version"]) }),
|
|
3492
3599
|
},
|
|
3493
3600
|
{
|
|
3494
3601
|
name: "update_requirement",
|
|
@@ -3503,6 +3610,7 @@ const mcpTools = [
|
|
|
3503
3610
|
title: mcpStr("Title"),
|
|
3504
3611
|
description: mcpStr("Description"),
|
|
3505
3612
|
acceptanceCriteria: mcpStr("Acceptance criteria"),
|
|
3613
|
+
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3506
3614
|
}, ["requirementId"]),
|
|
3507
3615
|
run: async (a) => {
|
|
3508
3616
|
const updates = mcpPick(a, ["status", "epicKey", "sprintId", "type", "title", "description", "acceptanceCriteria"]);
|
|
@@ -3513,6 +3621,10 @@ const mcpTools = [
|
|
|
3513
3621
|
}
|
|
3514
3622
|
const payload = { projectId: a.projectId, requirementId: a.requirementId, updates };
|
|
3515
3623
|
if (a.evidence) payload.evidence = a.evidence;
|
|
3624
|
+
if (a.attachments?.length) {
|
|
3625
|
+
if (!a.evidence) throw new McpToolError("attachments need evidence — images belong to an evidence entry");
|
|
3626
|
+
payload.attachments = await uploadEvidenceFiles(a.projectId, a.attachments);
|
|
3627
|
+
}
|
|
3516
3628
|
await mcpCall("updateRequirement", payload);
|
|
3517
3629
|
return { updated: a.requirementId, fields: Object.keys(updates) };
|
|
3518
3630
|
},
|
|
@@ -3644,6 +3756,25 @@ const mcpTools = [
|
|
|
3644
3756
|
inputSchema: mcpSchema({ status: mcpStr("Filter by status", { enum: ["pending", "approved", "rejected"] }) }),
|
|
3645
3757
|
run: async (a) => (await mcpCall("listPlanProposals", { projectId: a.projectId, status: a.status || null })).proposals,
|
|
3646
3758
|
},
|
|
3759
|
+
{
|
|
3760
|
+
name: "list_compliance_due",
|
|
3761
|
+
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.",
|
|
3762
|
+
inputSchema: mcpSchema({ sprintId: mcpStr("Sprint ID (default: the active sprint)") }),
|
|
3763
|
+
run: async (a) => mcpCall("listComplianceDue", { projectId: a.projectId, sprintId: a.sprintId || null }),
|
|
3764
|
+
},
|
|
3765
|
+
{
|
|
3766
|
+
name: "record_compliance_verification",
|
|
3767
|
+
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.",
|
|
3768
|
+
inputSchema: mcpSchema({
|
|
3769
|
+
requirementKey: mcpStr("Continuous requirement key"),
|
|
3770
|
+
result: mcpStr("passed or failed", { enum: ["passed", "failed"] }),
|
|
3771
|
+
evidence: mcpStr("What was checked in the sprint's diff and what was found (file:line), min 10 chars"),
|
|
3772
|
+
sprintId: mcpStr("Sprint ID (default: the active sprint)"),
|
|
3773
|
+
commit: mcpStr("Commit checked"),
|
|
3774
|
+
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3775
|
+
}, ["requirementKey", "result", "evidence"]),
|
|
3776
|
+
run: async (a) => mcpCall("recordSprintVerification", { projectId: a.projectId, ...mcpPick(a, ["requirementKey", "result", "evidence", "sprintId", "commit"]), attachments: await uploadEvidenceFiles(a.projectId, a.attachments) }),
|
|
3777
|
+
},
|
|
3647
3778
|
{
|
|
3648
3779
|
name: "notify_owner",
|
|
3649
3780
|
description: "Email the project owner (respects their opt-out). Used for the summary at the end of a scheduled agenda run. Plain text.",
|
|
@@ -3733,6 +3864,7 @@ const mcpTools = [
|
|
|
3733
3864
|
description: mcpStr("New description"),
|
|
3734
3865
|
mailNotify: mcpBool("Item email notifications on/off"),
|
|
3735
3866
|
skipTestVerification: mcpBool("Allow resolved without ready_for_test — only when no test applies. Evidence is still required."),
|
|
3867
|
+
attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
|
|
3736
3868
|
}, ["itemId"]),
|
|
3737
3869
|
run: async (a) => {
|
|
3738
3870
|
const u = mcpPick(a, ["status", "evidence", "assignedTo", "developer", "sprintId", "priority", "requirementKey", "description", "mailNotify"]);
|
|
@@ -3751,6 +3883,10 @@ const mcpTools = [
|
|
|
3751
3883
|
if (v.evidence.length) throw new McpToolError("Refusing status=resolved without evidence (min 10 chars). Cite the verification, or set ready_for_test instead.");
|
|
3752
3884
|
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.`);
|
|
3753
3885
|
}
|
|
3886
|
+
if (a.attachments?.length) {
|
|
3887
|
+
if (!a.evidence) throw new McpToolError("attachments need evidence — images belong to an evidence entry");
|
|
3888
|
+
u.attachments = await uploadEvidenceFiles(a.projectId, a.attachments);
|
|
3889
|
+
}
|
|
3754
3890
|
const r = await mcpCall("updateBacklogItems", { updates });
|
|
3755
3891
|
// The backend skips items it can't find or the caller can't access, instead of throwing.
|
|
3756
3892
|
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.`);
|
|
@@ -3805,7 +3941,7 @@ Work through these steps, then stop:
|
|
|
3805
3941
|
1. get_agenda. This is your task list.
|
|
3806
3942
|
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.
|
|
3807
3943
|
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.
|
|
3808
|
-
4. Approved requirements without tests and continuous requirements
|
|
3944
|
+
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.
|
|
3809
3945
|
5. Finish with notify_owner. Subject: "qa-tools daily run: <project> — <n> to review". Body, plain text, short:
|
|
3810
3946
|
- what you analysed and which signals you created (labels),
|
|
3811
3947
|
- the plan proposal you saved (or why none),
|