qatools-cli 1.2.12 → 1.2.14

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.
Files changed (2) hide show
  1. package/package.json +29 -27
  2. package/qatools.js +129 -37
package/package.json CHANGED
@@ -1,27 +1,29 @@
1
- {
2
- "name": "qatools-cli",
3
- "version": "1.2.12",
4
- "description": "CLI for QA Tools — requirements, epics, sprints, sessions, App Context sync, project agenda. The companion to qa-tools.com.",
5
- "scripts": {
6
- "release": "npm version patch --no-git-tag-version && npm publish",
7
- "release:minor": "npm version minor --no-git-tag-version && npm publish"
8
- },
9
- "bin": {
10
- "qatools": "qatools.js"
11
- },
12
- "files": [
13
- "qatools.js"
14
- ],
15
- "keywords": [
16
- "qa",
17
- "testing",
18
- "claude",
19
- "ai",
20
- "test-management"
21
- ],
22
- "license": "MIT",
23
- "dependencies": {
24
- "firebase": "^11.0.0",
25
- "commander": "^12.0.0"
26
- }
27
- }
1
+ {
2
+ "name": "qatools-cli",
3
+ "version": "1.2.14",
4
+ "description": "CLI for QA Tools — requirements, epics, sprints, sessions, App Context sync, project agenda. The companion to qa-tools.com.",
5
+ "scripts": {
6
+ "release": "npm version patch --no-git-tag-version && npm publish",
7
+ "release:minor": "npm version minor --no-git-tag-version && npm publish"
8
+ },
9
+ "bin": {
10
+ "qatools": "qatools.js"
11
+ },
12
+ "files": [
13
+ "qatools.js"
14
+ ],
15
+ "keywords": [
16
+ "qa",
17
+ "testing",
18
+ "claude",
19
+ "ai",
20
+ "test-management"
21
+ ],
22
+ "license": "MIT",
23
+ "dependencies": {
24
+ "@firebase/app": "^0.13.2",
25
+ "@firebase/auth": "^1.10.8",
26
+ "@firebase/functions": "^0.12.9",
27
+ "commander": "^12.0.0"
28
+ }
29
+ }
package/qatools.js CHANGED
@@ -1,13 +1,77 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  const { program } = require("commander");
4
- const { initializeApp } = require("firebase/app");
5
- const { getAuth, signInWithEmailAndPassword, signInWithCustomToken } = require("firebase/auth");
6
- const { getFunctions, httpsCallable, connectFunctionsEmulator } = require("firebase/functions");
4
+ const { initializeApp } = require("@firebase/app");
5
+ const { getAuth, signInWithEmailAndPassword, signInWithCustomToken } = require("@firebase/auth");
6
+ const { getFunctions, httpsCallable, connectFunctionsEmulator } = require("@firebase/functions");
7
7
  const fs = require("fs");
8
8
  const path = require("path");
9
9
  const http = require("http");
10
10
 
11
+ // cli.stale-agent-warning: agents must not run on old rules without noticing.
12
+ const CLI_VERSION = require("./package.json").version;
13
+ const SKILLS_MARKER = ".qatools-skills-version";
14
+ const UPDATE_CHECK_FILE = ".qatools-update-check";
15
+ function versionLess(a, b) {
16
+ const pa = String(a).split(".").map(n => parseInt(n, 10) || 0), pb = String(b).split(".").map(n => parseInt(n, 10) || 0);
17
+ for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0); }
18
+ return false;
19
+ }
20
+ // The repo's qa-tools skills: the nearest .claude/skills (from cwd upwards) that holds qa-*.md files.
21
+ function findQaSkillsDir(start = process.cwd()) {
22
+ let dir = path.resolve(start);
23
+ for (;;) {
24
+ const d = path.join(dir, ".claude", "skills");
25
+ try { if (fs.readdirSync(d).some(f => /^qa-.*\.md$/.test(f))) return d; } catch {}
26
+ const up = path.dirname(dir);
27
+ if (up === dir) return null;
28
+ dir = up;
29
+ }
30
+ }
31
+ async function latestPublishedVersion() {
32
+ const file = path.join(process.env.HOME || process.env.USERPROFILE || ".", UPDATE_CHECK_FILE);
33
+ try {
34
+ const c = JSON.parse(fs.readFileSync(file, "utf8"));
35
+ if (c.latest && Date.now() - c.checkedAt < 24 * 3600 * 1000) return c.latest;
36
+ } catch {}
37
+ try {
38
+ const ctrl = new AbortController();
39
+ const timer = setTimeout(() => ctrl.abort(), 2000);
40
+ const res = await fetch(process.env.QATOOLS_UPDATE_URL || "https://registry.npmjs.org/qatools-cli/latest", { signal: ctrl.signal });
41
+ clearTimeout(timer);
42
+ const latest = (await res.json()).version;
43
+ if (latest) try { fs.writeFileSync(file, JSON.stringify({ checkedAt: Date.now(), latest })); } catch {}
44
+ return latest || null;
45
+ } catch { return null; }
46
+ }
47
+ async function staleWarnings({ skipSkills = false } = {}) {
48
+ if (process.env.QATOOLS_NO_UPDATE_CHECK) return [];
49
+ const out = [];
50
+ const latest = await latestPublishedVersion();
51
+ if (latest && versionLess(CLI_VERSION, latest)) {
52
+ out.push(`qatools-cli ${CLI_VERSION} is out of date — ${latest} is available. Update: npm install -g qatools-cli@latest`);
53
+ }
54
+ const dir = skipSkills ? null : findQaSkillsDir();
55
+ if (dir) {
56
+ let written = "";
57
+ try { written = fs.readFileSync(path.join(dir, SKILLS_MARKER), "utf8").trim(); } catch {}
58
+ if (!written || versionLess(written, CLI_VERSION)) {
59
+ out.push(`The qa-tools skills in ${dir} were written by ${written ? `CLI ${written}` : "an unknown CLI version"}, older than ${CLI_VERSION}. Run: qatools init`);
60
+ }
61
+ }
62
+ return out;
63
+ }
64
+ let mcpWarnings = [];
65
+
66
+ // testing.evidence-commit: the commit evidence was verified on — the working directory's HEAD, or null outside git.
67
+ function currentGitCommit(cwd = process.cwd()) {
68
+ try {
69
+ const out = require("child_process").execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"], timeout: 3000 });
70
+ const sha = String(out).trim();
71
+ return /^[0-9a-f]{40}$/i.test(sha) ? sha : null;
72
+ } catch { return null; }
73
+ }
74
+
11
75
  const firebaseConfig = {
12
76
  projectId: "qatools-app",
13
77
  appId: "1:818706206429:web:647fe512fdba662cb4d534",
@@ -86,7 +150,7 @@ async function authenticate(options) {
86
150
  if (!data.id_token) throw new Error("Refresh failed");
87
151
 
88
152
  // Sign in with the ID token via signInWithCredential
89
- const { GoogleAuthProvider, signInWithCredential } = require('firebase/auth');
153
+ const { GoogleAuthProvider, signInWithCredential } = require('@firebase/auth');
90
154
  // First try: sign in directly by minting custom token via REST with proper callable format
91
155
  const mintRes = await fetch(`https://us-central1-qatools-app.cloudfunctions.net/mintCliToken`, {
92
156
  method: 'POST',
@@ -708,7 +772,8 @@ program
708
772
  const res = (await httpsCallable(functions, "uploadTestRun")({ projectId, run: meta, results })).data;
709
773
  console.log(`Uploaded run ${res.runId}.`);
710
774
  for (const r of res.requirements) {
711
- const change = r.statusAfter !== r.statusBefore ? ` ${r.statusBefore} → ${r.statusAfter}` : "";
775
+ const change = r.statusAfter !== r.statusBefore ? ` ${r.statusBefore} → ${r.statusAfter}`
776
+ : r.manualPending ? " stays implemented — manual tests in an approved protocol remain" : "";
712
777
  const sig = r.signal ? ` signal ${r.signal}` : "";
713
778
  console.log(` ${r.failed ? "✗" : "✓"} ${r.key}: ${r.ran - r.failed}/${r.ran} passed${r.skipped ? `, ${r.skipped} skipped` : ""}${change}${sig}`);
714
779
  }
@@ -937,6 +1002,8 @@ program
937
1002
  .description("List templates and their review status")
938
1003
  .option("--project <id>", "Target project ID (overrides default)")
939
1004
  .option("--status <status>", "Filter: draft, pending_review, approved, rejected")
1005
+ .option("--json", "Output as JSON with sections and test cases (stdout)")
1006
+ .option("-o, --output <file>", "Write JSON with sections and test cases to file")
940
1007
  .option("-e, --email <email>", "Login email")
941
1008
  .option("-p, --password <password>", "Login password")
942
1009
  .action(async (options) => {
@@ -947,8 +1014,15 @@ program
947
1014
 
948
1015
  const listTemplates = httpsCallable(functions, "listTemplates");
949
1016
  try {
950
- const result = await listTemplates({ projectId, status: options.status || null });
1017
+ const full = !!(options.json || options.output);
1018
+ const result = await listTemplates({ projectId, status: options.status || null, includeSections: full });
951
1019
  const templates = result.data.templates;
1020
+ if (options.json) { console.log(JSON.stringify(templates, null, 2)); process.exit(0); }
1021
+ if (options.output) {
1022
+ fs.writeFileSync(options.output, JSON.stringify(templates, null, 2));
1023
+ console.log(`Written ${templates.length} template${templates.length !== 1 ? "s" : ""} to ${options.output}`);
1024
+ process.exit(0);
1025
+ }
952
1026
  if (templates.length === 0) {
953
1027
  console.log("No templates found.");
954
1028
  } else {
@@ -973,8 +1047,9 @@ program
973
1047
  .option("--epic <key>", "Only reqs linked to this epic")
974
1048
  .option("--no-epic", "Only reqs WITHOUT an epic")
975
1049
  .option("--type <type>", "Filter by type: functional, non-functional")
976
- .option("--with-coverage", "Only reqs that have at least one test case in any template")
977
- .option("--without-coverage", "Only reqs with NO test coverage")
1050
+ .option("--with-coverage", "Only reqs with test coverage (see --coverage-source)")
1051
+ .option("--without-coverage", "Only reqs with NO test coverage (see --coverage-source)")
1052
+ .option("--coverage-source <source>", "What counts as coverage: template (manual test cases), automated (qatools test-report runs) or any", "any")
978
1053
  .option("--include-superseded", "Include superseded reqs (hidden by default)")
979
1054
  .option("--json", "Output as JSON to stdout (machine-readable)")
980
1055
  .option("-o, --output <file>", "Write JSON output to file")
@@ -1009,27 +1084,21 @@ program
1009
1084
  // Type
1010
1085
  if (options.type) reqs = reqs.filter(r => r.type === options.type);
1011
1086
 
1012
- // Coverage filters require loading templates
1013
- if (options.withCoverage || options.withoutCoverage) {
1014
- const listTemplates = httpsCallable(functions, "listTemplates");
1015
- const tplResult = await listTemplates({ projectId, status: null });
1016
- // listTemplates returns summary only — we need full templates for test cases
1017
- // Use the full templates list via a different path: load each template (or rely on coverage server-side later)
1018
- // For now: scan template summaries for requirementKey if present, otherwise we have to fall back
1019
- const covered = new Set();
1020
- for (const t of (tplResult.data.templates || [])) {
1021
- // Some template responses include sections, others only summaries
1022
- for (const sec of (t.sections || [])) {
1023
- for (const test of (sec.tests || [])) {
1024
- if (test.requirementKey) covered.add(test.requirementKey);
1025
- }
1026
- }
1027
- }
1028
- if (options.withCoverage) reqs = reqs.filter(r => covered.has(r.key));
1029
- if (options.withoutCoverage) reqs = reqs.filter(r => !covered.has(r.key));
1030
- if (covered.size === 0 && (options.withCoverage || options.withoutCoverage)) {
1031
- console.error("Note: listTemplates returned no test-case data. Coverage filter may be unreliable. Use the web app for accurate coverage.");
1032
- }
1087
+ // Coverage per key from the backend: manual test cases + latest automated run (cli.requirement-coverage)
1088
+ const source = options.coverageSource || "any";
1089
+ if (!["template", "automated", "any"].includes(source)) { console.error("--coverage-source must be template, automated or any"); process.exit(1); }
1090
+ const wantsCoverage = options.withCoverage || options.withoutCoverage || options.json || options.output;
1091
+ if (wantsCoverage) {
1092
+ const { data } = await httpsCallable(functions, "requirementCoverage")({ projectId });
1093
+ const none = { manualTests: 0, approvedManualTests: 0, automated: null };
1094
+ reqs = reqs.map(r => ({ ...r, coverage: data.coverage[r.key] || none }));
1095
+ const covered = (r) => {
1096
+ const c = r.coverage;
1097
+ const manual = c.manualTests > 0, auto = !!c.automated;
1098
+ return source === "template" ? manual : source === "automated" ? auto : manual || auto;
1099
+ };
1100
+ if (options.withCoverage) reqs = reqs.filter(covered);
1101
+ if (options.withoutCoverage) reqs = reqs.filter(r => !covered(r));
1033
1102
  }
1034
1103
 
1035
1104
  // Output
@@ -1045,7 +1114,8 @@ program
1045
1114
  for (const r of reqs) {
1046
1115
  const badge = r.status === "rejected" ? "❌" : r.status === "approved" ? "✅" : r.status === "in_progress" ? "🔨" : r.status === "tested" ? "🟢" : r.status === "implemented" ? "🟡" : r.status === "superseded" ? "🗑" : "📝";
1047
1116
  const epic = r.epicKey ? ` epic:${r.epicKey}` : ' (no epic)';
1048
- console.log(` ${badge} [${r.key}]${epic} ${r.title} (${r.status})`);
1117
+ const cov = r.coverage ? ` [manual ${r.coverage.manualTests}${r.coverage.automated ? `, automated ${r.coverage.automated.ran - r.coverage.automated.failed}/${r.coverage.automated.ran}` : ""}]` : "";
1118
+ console.log(` ${badge} [${r.key}]${epic} ${r.title} (${r.status})${cov}`);
1049
1119
  if (r.reviewComment) console.log(` 💬 ${r.reviewComment}`);
1050
1120
  }
1051
1121
  }
@@ -1461,6 +1531,8 @@ program
1461
1531
  .option("--assigned <email>", "Set assignee: a member's email, 'me' (you, or the Claude account for an API key), or empty string to clear")
1462
1532
  .option("--evidence <text>", "REQUIRED when status=implemented or tested. Cite test output, file:line, expected vs actual, or 'no test applies because <reason>'.")
1463
1533
  .option("--attach <files...>", "Image file(s) as evidence (png/jpg/webp/gif, max 4 MB each)")
1534
+ .option("--commit <sha>", "Commit the evidence was verified on (default: git HEAD of the current directory)")
1535
+ .option("--no-commit", "Do not record a commit with the evidence")
1464
1536
  .option("--epic <key>", "Set epicKey")
1465
1537
  .option("--sprint <id>", "Set sprintId (use empty string to clear)")
1466
1538
  .option("--type <type>", "Set type (functional/non-functional)")
@@ -1535,7 +1607,11 @@ program
1535
1607
  if (!evidenceById[requirementId]) throw new Error("--attach needs --evidence (images belong to an evidence entry)");
1536
1608
  payload.attachments = await uploadEvidenceFiles(projectId, options.attach);
1537
1609
  }
1538
- if (evidenceById[requirementId]) payload.evidence = evidenceById[requirementId];
1610
+ if (evidenceById[requirementId]) {
1611
+ payload.evidence = evidenceById[requirementId];
1612
+ const commit = options.commit === false ? null : (typeof options.commit === "string" ? options.commit : currentGitCommit());
1613
+ if (commit) payload.commit = commit;
1614
+ }
1539
1615
  await updateReq(payload);
1540
1616
  ok++;
1541
1617
  process.stdout.write(`\r Updated ${ok}, failed ${failed} / ${Object.keys(updates).length}`);
@@ -2262,8 +2338,8 @@ program
2262
2338
  });
2263
2339
  const authData = await authRes.json();
2264
2340
  if (authData.result?.customToken) {
2265
- const { signInWithCustomToken } = require("firebase/auth");
2266
- const { getAuth } = require("firebase/auth");
2341
+ const { signInWithCustomToken } = require("@firebase/auth");
2342
+ const { getAuth } = require("@firebase/auth");
2267
2343
  await signInWithCustomToken(getAuth(), authData.result.customToken);
2268
2344
  const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
2269
2345
  const config = { apiKey: options.apiKey, projectId: authData.result.projectId, projectName: authData.result.projectName, email: authData.result.email };
@@ -2843,6 +2919,7 @@ If the verification fails: do NOT mark tested. Go back to step 1, find the discr
2843
2919
  for (const [filename, content] of Object.entries(skills)) {
2844
2920
  fs.writeFileSync(path.join(skillsDir, filename), content);
2845
2921
  }
2922
+ fs.writeFileSync(path.join(skillsDir, SKILLS_MARKER), CLI_VERSION + "\n");
2846
2923
  console.log(" ✓ qa-purpose.md (READ FIRST)");
2847
2924
  console.log(" ✓ qa-loop.md");
2848
2925
  console.log(" ✓ qa-requirement-analyst.md");
@@ -3564,7 +3641,10 @@ const mcpTools = [
3564
3641
  name: "get_agenda",
3565
3642
  description: "What to work on next in the project (same data as `qatools next`): open signals, requirements awaiting work, sessions awaiting analysis.",
3566
3643
  inputSchema: mcpSchema(),
3567
- run: async (a) => mcpCall("getProjectAgenda", { projectId: a.projectId }),
3644
+ run: async (a) => {
3645
+ const agenda = await mcpCall("getProjectAgenda", { projectId: a.projectId });
3646
+ return mcpWarnings.length ? { warnings: mcpWarnings, ...agenda } : agenda;
3647
+ },
3568
3648
  },
3569
3649
  {
3570
3650
  name: "get_app_context",
@@ -3625,6 +3705,7 @@ const mcpTools = [
3625
3705
  description: mcpStr("Description"),
3626
3706
  acceptanceCriteria: mcpStr("Acceptance criteria"),
3627
3707
  attachments: mcpStrArray("Local image file paths (png/jpg/webp/gif, max 4 MB) to attach to the evidence, e.g. screenshots"),
3708
+ commit: mcpStr("Commit the evidence was verified on. Default: git HEAD of the server's working directory; empty string to leave it out"),
3628
3709
  }, ["requirementId"]),
3629
3710
  run: async (a) => {
3630
3711
  const updates = mcpPick(a, ["status", "assignedTo", "epicKey", "sprintId", "type", "title", "description", "acceptanceCriteria"]);
@@ -3634,7 +3715,11 @@ const mcpTools = [
3634
3715
  throw new McpToolError(`Refusing status=${updates.status} without evidence (min 10 chars). Cite the verification, or use a status that does not claim done.`);
3635
3716
  }
3636
3717
  const payload = { projectId: a.projectId, requirementId: a.requirementId, updates };
3637
- if (a.evidence) payload.evidence = a.evidence;
3718
+ if (a.evidence) {
3719
+ payload.evidence = a.evidence;
3720
+ const commit = a.commit !== undefined ? a.commit : currentGitCommit();
3721
+ if (commit) payload.commit = commit;
3722
+ }
3638
3723
  if (a.attachments?.length) {
3639
3724
  if (!a.evidence) throw new McpToolError("attachments need evidence — images belong to an evidence entry");
3640
3725
  payload.attachments = await uploadEvidenceFiles(a.projectId, a.attachments);
@@ -4111,7 +4196,7 @@ async function mcpHandle(msg, defaultProjectId) {
4111
4196
  protocolVersion: MCP_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSIONS[0],
4112
4197
  capabilities: { tools: { listChanged: false }, prompts: { listChanged: false } },
4113
4198
  serverInfo: { name: "qatools", version: require("./package.json").version },
4114
- instructions: MCP_INSTRUCTIONS,
4199
+ instructions: MCP_INSTRUCTIONS + (mcpWarnings.length ? "\n- OUT OF DATE — tell the user before anything else: " + mcpWarnings.join(" ") : ""),
4115
4200
  };
4116
4201
  }
4117
4202
  if (method === "ping") return {};
@@ -4160,6 +4245,8 @@ program
4160
4245
  console.info = (...a) => console.error(...a);
4161
4246
 
4162
4247
  await authenticate(options);
4248
+ mcpWarnings = await staleWarnings();
4249
+ for (const w of mcpWarnings) console.error(`⚠ ${w}`);
4163
4250
  const defaultProjectId = options.project || getCredentials()?.projectId || null;
4164
4251
  console.error(`qatools MCP server ready${defaultProjectId ? ` (default project ${defaultProjectId})` : ""}`);
4165
4252
 
@@ -4184,4 +4271,9 @@ program
4184
4271
  rl.on("close", () => process.exit(0));
4185
4272
  });
4186
4273
 
4187
- program.parse();
4274
+ program.hook("preAction", async (_root, cmd) => {
4275
+ if (cmd.name() === "mcp") return; // the MCP server reports through instructions and get_agenda
4276
+ for (const w of await staleWarnings({ skipSkills: cmd.name() === "init" })) console.error(`⚠ ${w}`);
4277
+ });
4278
+
4279
+ program.parseAsync();