qatools-cli 1.2.3 → 1.2.5

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 +1 -1
  2. package/qatools.js +262 -7
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "qatools-cli",
3
- "version": "1.2.3",
3
+ "version": "1.2.5",
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
@@ -21,16 +21,20 @@ const app = initializeApp(firebaseConfig);
21
21
  const auth = getAuth(app);
22
22
  const functions = getFunctions(app);
23
23
 
24
+ // Project from a QATOOLS_API_KEY env-var login: applies to this process only and is never written to
25
+ // ~/.qatools, so e.g. a scheduled run with a propose-only key can't change the user's default project.
26
+ let envKeyProject = null;
27
+
24
28
  // Load credentials from ~/.qatools or env vars
25
29
  function getCredentials() {
26
30
  const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
31
+ let creds = null;
27
32
  if (fs.existsSync(configPath)) {
28
- return JSON.parse(fs.readFileSync(configPath, "utf-8"));
29
- }
30
- if (process.env.QATOOLS_EMAIL && process.env.QATOOLS_PASSWORD) {
31
- return { email: process.env.QATOOLS_EMAIL, password: process.env.QATOOLS_PASSWORD };
33
+ creds = JSON.parse(fs.readFileSync(configPath, "utf-8"));
34
+ } else if (process.env.QATOOLS_EMAIL && process.env.QATOOLS_PASSWORD) {
35
+ creds = { email: process.env.QATOOLS_EMAIL, password: process.env.QATOOLS_PASSWORD };
32
36
  }
33
- return null;
37
+ return envKeyProject ? { ...(creds || {}), ...envKeyProject } : creds;
34
38
  }
35
39
 
36
40
  async function authenticate(options) {
@@ -49,8 +53,11 @@ async function authenticate(options) {
49
53
  const authData = await authRes.json();
50
54
  if (authData.result?.customToken) {
51
55
  await signInWithCustomToken(auth, authData.result.customToken);
52
- // Set projectId from API key response if not already configured
53
- if (authData.result.projectId && (!creds?.projectId || process.env.QATOOLS_API_KEY)) {
56
+ if (process.env.QATOOLS_API_KEY) {
57
+ // Env-var key: the key's project for this process only — ~/.qatools is left untouched.
58
+ envKeyProject = { projectId: authData.result.projectId, projectName: authData.result.projectName, apiKey };
59
+ } else if (authData.result.projectId && !creds?.projectId) {
60
+ // Stored key without a project yet: remember the key's project.
54
61
  const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
55
62
  const existing = creds || {};
56
63
  existing.projectId = authData.result.projectId;
@@ -587,6 +594,198 @@ program
587
594
  process.exit(0);
588
595
  });
589
596
 
597
+ // ─── qatools test-report (testing.ci-evidence) ──────────────────────────────
598
+ // Stack-agnostic: JUnit XML (what nearly every test runner can emit) or a small JSON format.
599
+ // A test names its requirement with a JUnit property requirementKey, or with "[req:<key>]" in
600
+ // its name/classname.
601
+
602
+ const xmlDecode = (s) => String(s).replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
603
+ const xmlAttrs = (s) => { const a = {}; for (const m of String(s).matchAll(/([\w:.-]+)\s*=\s*"([^"]*)"/g)) a[m[1]] = xmlDecode(m[2]); return a; };
604
+ const REQ_TAG = /\[req:([\w.\-/]+)\]/i;
605
+
606
+ function parseJUnit(xml) {
607
+ const out = [];
608
+ for (const m of xml.matchAll(/<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g)) {
609
+ const attrs = xmlAttrs(m[1]);
610
+ const body = m[2] || "";
611
+ const name = [attrs.classname, attrs.name].filter(Boolean).join(" › ") || "(unnamed test)";
612
+ let requirementKey = "";
613
+ for (const p of body.matchAll(/<property\b([^>]*?)\/?>/g)) {
614
+ const pa = xmlAttrs(p[1]);
615
+ if (/^requirement[-_]?key$/i.test(pa.name || "")) requirementKey = pa.value || "";
616
+ }
617
+ if (!requirementKey) requirementKey = (name.match(REQ_TAG) || [])[1] || "";
618
+ const fail = body.match(/<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/);
619
+ const skipped = /<skipped\b/.test(body);
620
+ const status = fail ? "fail" : skipped ? "skip" : "pass";
621
+ const message = fail ? (xmlAttrs(fail[2]).message || xmlDecode((fail[3] || "").replace(/<!\[CDATA\[|\]\]>/g, "")).trim().split("\n")[0]) : "";
622
+ out.push({ name: name.replace(REQ_TAG, "").trim(), requirementKey, status, message: (message || "").slice(0, 500) });
623
+ }
624
+ return out;
625
+ }
626
+
627
+ function parseTestJson(data) {
628
+ const list = Array.isArray(data) ? data : (data.results || []);
629
+ return list.map(r => {
630
+ const name = String(r.name || r.title || "(unnamed test)");
631
+ const s = String(r.status || "").toLowerCase();
632
+ const status = ["pass", "passed", "ok", "success"].includes(s) ? "pass" : ["skip", "skipped", "pending", "todo"].includes(s) ? "skip" : "fail";
633
+ return { name: name.replace(REQ_TAG, "").trim(), requirementKey: String(r.requirementKey || (name.match(REQ_TAG) || [])[1] || ""), status, message: String(r.message || r.error || "").slice(0, 500) };
634
+ });
635
+ }
636
+
637
+ function ciRunMeta(options) {
638
+ const env = process.env;
639
+ const git = (args) => { try { return require("child_process").execSync(`git ${args}`, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; } };
640
+ const commit = options.commit || env.GITHUB_SHA || env.CI_COMMIT_SHA || env.BUILD_SOURCEVERSION || env.BITBUCKET_COMMIT || git("rev-parse HEAD");
641
+ const branch = options.branch || env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME || env.CI_COMMIT_REF_NAME || env.BUILD_SOURCEBRANCHNAME || env.BITBUCKET_BRANCH || git("rev-parse --abbrev-ref HEAD");
642
+ const url = options.url || (env.GITHUB_RUN_ID ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : env.CI_JOB_URL || "");
643
+ const source = env.GITHUB_ACTIONS ? "github-actions" : env.GITLAB_CI ? "gitlab-ci" : env.TF_BUILD ? "azure-devops" : env.BITBUCKET_BUILD_NUMBER ? "bitbucket" : env.CI ? "ci" : "local";
644
+ return { commit, branch, url, source };
645
+ }
646
+
647
+ program
648
+ .command("test-report")
649
+ .description("Upload test results (JUnit XML or JSON) as evidence on requirements. Tag tests with a requirementKey property or [req:<key>] in the name.")
650
+ .requiredOption("-f, --file <path>", "JUnit XML or JSON results file")
651
+ .option("--format <format>", "junit or json (default: from file extension)")
652
+ .option("--commit <sha>", "Commit (default: from CI env or git)")
653
+ .option("--branch <name>", "Branch (default: from CI env or git)")
654
+ .option("--url <url>", "Link to the CI run (default: from CI env)")
655
+ .option("--dry-run", "Parse and show the requirement mapping without uploading")
656
+ .option("--project <id>", "Target project ID (overrides default)")
657
+ .option("-e, --email <email>", "Login email")
658
+ .option("-p, --password <password>", "Login password")
659
+ .action(async (options) => {
660
+ const filePath = path.resolve(options.file);
661
+ if (!fs.existsSync(filePath)) { console.error(`File not found: ${filePath}`); process.exit(1); }
662
+ const text = fs.readFileSync(filePath, "utf-8");
663
+ const format = options.format || (/\.json$/i.test(filePath) ? "json" : "junit");
664
+ let results;
665
+ try {
666
+ results = format === "json" ? parseTestJson(JSON.parse(text)) : parseJUnit(text);
667
+ } catch (e) {
668
+ console.error(`Could not parse ${format}: ${e.message}`);
669
+ process.exit(1);
670
+ }
671
+ if (results.length === 0) { console.error("No test results found in the file."); process.exit(1); }
672
+ const meta = ciRunMeta(options);
673
+ const tagged = results.filter(r => r.requirementKey);
674
+ console.log(`${results.length} test(s): ${results.filter(r => r.status === "pass").length} pass, ${results.filter(r => r.status === "fail").length} fail, ${results.filter(r => r.status === "skip").length} skip — ${tagged.length} tagged with a requirementKey`);
675
+
676
+ if (options.dryRun) {
677
+ const byKey = {};
678
+ for (const r of tagged) (byKey[r.requirementKey] = byKey[r.requirementKey] || []).push(r);
679
+ for (const [k, rs] of Object.entries(byKey)) console.log(` ${k}: ${rs.map(r => `${r.status === "pass" ? "✓" : r.status === "fail" ? "✗" : "–"} ${r.name}`).join(", ")}`);
680
+ if (tagged.length < results.length) console.log(` (untagged: ${results.length - tagged.length})`);
681
+ console.log(`Run: ${meta.source} ${meta.commit ? meta.commit.slice(0, 8) : "(no commit)"} ${meta.branch || ""}`);
682
+ process.exit(0);
683
+ }
684
+
685
+ await authenticate(options);
686
+ const creds = getCredentials();
687
+ const projectId = options.project || creds?.projectId;
688
+ if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
689
+ try {
690
+ const res = (await httpsCallable(functions, "uploadTestRun")({ projectId, run: meta, results })).data;
691
+ console.log(`Uploaded run ${res.runId}.`);
692
+ for (const r of res.requirements) {
693
+ const change = r.statusAfter !== r.statusBefore ? ` ${r.statusBefore} → ${r.statusAfter}` : "";
694
+ const sig = r.signal ? ` signal ${r.signal}` : "";
695
+ console.log(` ${r.failed ? "✗" : "✓"} ${r.key}: ${r.ran - r.failed}/${r.ran} passed${r.skipped ? `, ${r.skipped} skipped` : ""}${change}${sig}`);
696
+ }
697
+ if (res.orphanCount) console.log(` ${res.orphanCount} test(s) without a known requirementKey were not linked.`);
698
+ // Exit 0 when the upload worked: the test step itself already failed the build if tests failed.
699
+ process.exit(0);
700
+ } catch (e) {
701
+ console.error("Failed:", e.message);
702
+ process.exit(1);
703
+ }
704
+ });
705
+
706
+ // ─── Compliance per sprint (compliance.sprint-verification-via-cli) ─────────
707
+
708
+ // Commits and changed files since a date, from the git repo in the current directory ("" if none).
709
+ function gitChangesSince(date) {
710
+ if (!date) return { commits: [], files: [] };
711
+ const git = (args) => { try { return require("child_process").execSync(`git ${args}`, { stdio: ["ignore", "pipe", "ignore"], maxBuffer: 32 * 1024 * 1024 }).toString(); } catch { return ""; } };
712
+ const commits = git(`log --since=${date} --pretty=format:%h%x09%s`).split("\n").filter(Boolean);
713
+ const files = [...new Set(git(`log --since=${date} --name-only --pretty=format:`).split("\n").map(s => s.trim()).filter(Boolean))].sort();
714
+ return { commits, files };
715
+ }
716
+
717
+ program
718
+ .command("compliance-check")
719
+ .description("List the sprint's continuous compliance requirements, their verification status and the git changes since the sprint started (run in the repo)")
720
+ .option("--sprint <id>", "Sprint ID (default: the active sprint)")
721
+ .option("--json", "Output JSON (for Claude / CI)")
722
+ .option("--project <id>", "Target project ID (overrides default)")
723
+ .option("-e, --email <email>", "Login email")
724
+ .option("-p, --password <password>", "Login password")
725
+ .action(async (options) => {
726
+ await authenticate(options);
727
+ const creds = getCredentials();
728
+ const projectId = options.project || creds?.projectId;
729
+ if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
730
+ try {
731
+ const res = (await httpsCallable(functions, "listComplianceDue")({ projectId, sprintId: options.sprint || null })).data;
732
+ const changes = gitChangesSince(res.sprint.startDate);
733
+ if (options.json) { console.log(JSON.stringify({ ...res, changes }, null, 2)); process.exit(0); }
734
+ 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} compliance requirement(s) verified\n`);
736
+ for (const r of res.requirements) {
737
+ const st = r.verification ? (r.verification.result === "passed" ? "✓ passed" : "✗ failed") : "… to verify";
738
+ console.log(` ${st.padEnd(13)} [${r.key}] ${r.title}`);
739
+ }
740
+ 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"}.`);
741
+ for (const f of changes.files.slice(0, 40)) console.log(` ${f}`);
742
+ if (changes.files.length > 40) console.log(` … (+${changes.files.length - 40}, use --json for all)`);
743
+ console.log(`\nRecord each result: qatools compliance-record --key <key> --result passed|failed --evidence "<what you checked, file:line>"`);
744
+ } catch (e) {
745
+ console.error("Failed:", e.message);
746
+ process.exit(1);
747
+ }
748
+ process.exit(0);
749
+ });
750
+
751
+ program
752
+ .command("compliance-record")
753
+ .description("Record a compliance requirement's verification for the sprint (evidence required). failed creates an AVV signal.")
754
+ .requiredOption("--key <requirementKey>", "Compliance requirement key")
755
+ .requiredOption("--result <result>", "passed or failed")
756
+ .requiredOption("--evidence <text>", "What was checked in the sprint's diff and what was found (file:line), min 10 chars")
757
+ .option("--sprint <id>", "Sprint ID (default: the active sprint)")
758
+ .option("--commit <sha>", "Commit checked (default: git HEAD)")
759
+ .option("--project <id>", "Target project ID (overrides default)")
760
+ .option("-e, --email <email>", "Login email")
761
+ .option("-p, --password <password>", "Login password")
762
+ .action(async (options) => {
763
+ await authenticate(options);
764
+ const creds = getCredentials();
765
+ const projectId = options.project || creds?.projectId;
766
+ if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
767
+ let commit = options.commit || "";
768
+ if (!commit) { try { commit = require("child_process").execSync("git rev-parse HEAD", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { /* not a repo */ } }
769
+ try {
770
+ const res = (await httpsCallable(functions, "recordSprintVerification")({ projectId, sprintId: options.sprint || null, requirementKey: options.key, result: options.result, evidence: options.evidence, commit })).data;
771
+ console.log(`Recorded ${res.requirementKey}: ${res.result} for sprint ${res.sprintName}${res.signal ? ` — signal ${res.signal}` : ""}.`);
772
+ } catch (e) {
773
+ console.error("Failed:", e.message);
774
+ process.exit(1);
775
+ }
776
+ process.exit(0);
777
+ });
778
+
779
+ program
780
+ .command("agenda-run-prompt")
781
+ .description("Print the unattended daily-agenda-run instructions, for: claude -p \"$(qatools agenda-run-prompt)\"")
782
+ .option("--project <id>", "Project ID to name in the instructions (default: the key's project)")
783
+ .action((options) => {
784
+ // No login needed — it only prints text. Same text as the MCP prompt daily_agenda_run.
785
+ console.log(dailyAgendaRunPrompt(options.project));
786
+ process.exit(0);
787
+ });
788
+
590
789
  program
591
790
  .command("plan-proposals")
592
791
  .description("List sprint-plan proposals (pending ones are approved in the web app: Sprints → Plan proposals)")
@@ -3167,6 +3366,9 @@ program
3167
3366
  const config = { apiKey: options.apiKey, projectId, projectName, email };
3168
3367
  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
3169
3368
  console.log(`Logged in as Claude for project: ${projectName}`);
3369
+ if (authData.result.scope === "propose-only") {
3370
+ console.log("Scope: propose-only — this key can read and propose, but never change status, plan, delete or change members.");
3371
+ }
3170
3372
  console.log(`Project ID: ${projectId}`);
3171
3373
  process.exit(0);
3172
3374
  }
@@ -3515,6 +3717,33 @@ const mcpTools = [
3515
3717
  inputSchema: mcpSchema({ status: mcpStr("Filter by status", { enum: ["pending", "approved", "rejected"] }) }),
3516
3718
  run: async (a) => (await mcpCall("listPlanProposals", { projectId: a.projectId, status: a.status || null })).proposals,
3517
3719
  },
3720
+ {
3721
+ name: "list_compliance_due",
3722
+ description: "The sprint's continuous compliance 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
+ inputSchema: mcpSchema({ sprintId: mcpStr("Sprint ID (default: the active sprint)") }),
3724
+ run: async (a) => mcpCall("listComplianceDue", { projectId: a.projectId, sprintId: a.sprintId || null }),
3725
+ },
3726
+ {
3727
+ name: "record_compliance_verification",
3728
+ description: "Record the result of checking a compliance 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
+ inputSchema: mcpSchema({
3730
+ requirementKey: mcpStr("Compliance requirement key"),
3731
+ result: mcpStr("passed or failed", { enum: ["passed", "failed"] }),
3732
+ evidence: mcpStr("What was checked in the sprint's diff and what was found (file:line), min 10 chars"),
3733
+ sprintId: mcpStr("Sprint ID (default: the active sprint)"),
3734
+ commit: mcpStr("Commit checked"),
3735
+ }, ["requirementKey", "result", "evidence"]),
3736
+ run: async (a) => mcpCall("recordSprintVerification", { projectId: a.projectId, ...mcpPick(a, ["requirementKey", "result", "evidence", "sprintId", "commit"]) }),
3737
+ },
3738
+ {
3739
+ name: "notify_owner",
3740
+ description: "Email the project owner (respects their opt-out). Used for the summary at the end of a scheduled agenda run. Plain text.",
3741
+ inputSchema: mcpSchema({
3742
+ subject: mcpStr("Email subject"),
3743
+ message: mcpStr("Plain-text body"),
3744
+ }, ["subject", "message"]),
3745
+ run: async (a) => mcpCall("notifyUser", { projectId: a.projectId, to: "owner", subject: a.subject, message: a.message }),
3746
+ },
3518
3747
  {
3519
3748
  name: "reject_plan_proposal",
3520
3749
  description: "Reject (withdraw) a pending sprint-plan proposal, e.g. one you created that is superseded. Nothing gets planned. There is no approve tool: approval is a human decision in the qa-tools web app.",
@@ -3656,6 +3885,26 @@ const mcpTools = [
3656
3885
  },
3657
3886
  ];
3658
3887
 
3888
+ // automation.daily-agenda-run: the unattended procedure. Shared by the MCP prompt daily_agenda_run and
3889
+ // `qatools agenda-run-prompt` (for `claude -p`), so both always say the same thing.
3890
+ function dailyAgendaRunPrompt(projectId) {
3891
+ const a = { projectId };
3892
+ return `You are running UNATTENDED on the qa-tools project${a.projectId ? ` ${a.projectId}` : ""}. Nobody will answer questions. Use a propose-only key: the backend refuses status changes, planning, deletes and member changes — if a tool is refused, note it in the summary and move on; never try another way.
3893
+
3894
+ Work through these steps, then stop:
3895
+
3896
+ 1. get_agenda. This is your task list.
3897
+ 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
+ 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 compliance 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 compliance keys in the summary.
3900
+ 5. Finish with notify_owner. Subject: "qa-tools daily run: <project> — <n> to review". Body, plain text, short:
3901
+ - what you analysed and which signals you created (labels),
3902
+ - the plan proposal you saved (or why none),
3903
+ - anything that was refused or that needs a human decision,
3904
+ - where to look: qa-tools → Sprints → Plan proposals, Backlog.
3905
+ If there was nothing to do, still send a one-line summary saying so.`;
3906
+ }
3907
+
3659
3908
  // Prompts (sprint.ai-planning): ready-made workflows the user picks in the client, e.g. the "+" menu in Claude Desktop.
3660
3909
  const mcpPrompts = [
3661
3910
  {
@@ -3682,6 +3931,12 @@ Follow these steps in order:
3682
3931
  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.
3683
3932
  6. End with get_sprint_items for each affected sprint so the user can see the result.`,
3684
3933
  },
3934
+ {
3935
+ name: "daily_agenda_run",
3936
+ description: "Unattended run (automation.daily-agenda-run): work through the project agenda, propose — never apply — and email the owner a summary.",
3937
+ arguments: [{ name: "projectId", description: "Project ID (default: configured project)", required: false }],
3938
+ text: (a) => dailyAgendaRunPrompt(a.projectId),
3939
+ },
3685
3940
  ];
3686
3941
 
3687
3942
  function mcpValidateArgs(tool, args) {