qatools-cli 1.2.40 → 1.2.42

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/brief.js CHANGED
@@ -1,8 +1,10 @@
1
1
  // context.session-brief: the short brief a Claude session starts with. Pure: data in, text out (at most 30 lines).
2
2
  const MAX_LINES = 30;
3
3
 
4
- function renderBrief({ projectName = "", requirements = [], agenda = null, requests = [], branch = "", branchKeys = [], main = "" }) {
4
+ function renderBrief({ projectName = "", requirements = [], agenda = null, requests = [], branch = "", branchKeys = [], main = "", warnings = [] }) {
5
5
  const lines = [`qa-tools brief${projectName ? ` — ${projectName}` : ""} (read this before you start)`];
6
+ // cli.self-upgrade: out of date first — upgrade yourself (qa-purpose skill: Keeping qa-tools current)
7
+ for (const w of warnings.slice(0, 2)) lines.push(`⚠ ${w} Upgrade yourself, then tell the person in one line.`);
6
8
  const verified = (r) => r.status === "implemented" || r.status === "tested";
7
9
  const who = (e) => /^claude@[^@]+\.qatools$/i.test(String(e || "")) ? "Claude" : (e || "nobody");
8
10
 
package/mcp-core.js CHANGED
@@ -1080,7 +1080,7 @@ async function mcpHandle(msg, defaultProjectId) {
1080
1080
  protocolVersion: MCP_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSIONS[0],
1081
1081
  capabilities: { tools: { listChanged: false }, prompts: { listChanged: false } },
1082
1082
  serverInfo: { name: "qatools", version: env.version || "" },
1083
- instructions: instructions + (warnings().length ? "\n- OUT OF DATE — tell the user before anything else: " + warnings().join(" ") : ""),
1083
+ instructions: instructions + (warnings().length ? "\n- OUT OF DATE: " + warnings().join(" ") + " Upgrade yourself (npm install -g qatools-cli@latest, then qatools init in the repo, commit the .claude changes) and tell the user in one line — unless this is an unattended run, which never upgrades mid-run." : ""),
1084
1084
  };
1085
1085
  }
1086
1086
  if (method === "ping") return {};
package/own-login.js ADDED
@@ -0,0 +1,78 @@
1
+ // cli.claude-own-login: Claude works in qa-tools as Claude, with the project's own key — never on the person's login.
2
+ // `qatools init --claude-login` (run once by the person, signed in as themselves) stores the project's Claude key in a
3
+ // project-own login folder outside the repo, marks the repo with its project (.claude/qatools-project.json, no secret)
4
+ // and points Claude Code's qatools MCP server for the repo at that folder. When Claude runs qatools in a marked repo
5
+ // (Claude Code sets CLAUDECODE=1 for its commands), the CLI uses that login — and refuses rather than fall back to
6
+ // the person's. A person running qatools in a terminal keeps their own login.
7
+ const fs = require("fs");
8
+ const path = require("path");
9
+ const os = require("os");
10
+
11
+ const MARKER = path.join(".claude", "qatools-project.json");
12
+
13
+ // The project-own login folder: its .qatools holds only Claude's key for that project
14
+ const projectHome = (projectId, home = os.homedir()) => path.join(home, ".qatools-projects", String(projectId).replace(/[^A-Za-z0-9_-]/g, ""));
15
+
16
+ // The nearest repo marker from cwd upwards → { projectId, projectName, dir } or null
17
+ function findProjectMarker(cwd = process.cwd()) {
18
+ let dir = path.resolve(cwd);
19
+ for (;;) {
20
+ const f = path.join(dir, MARKER);
21
+ try {
22
+ const m = JSON.parse(fs.readFileSync(f, "utf8"));
23
+ if (m && typeof m.projectId === "string" && m.projectId) return { projectId: m.projectId, projectName: m.projectName || "", dir };
24
+ } catch {}
25
+ const up = path.dirname(dir);
26
+ if (up === dir) return null;
27
+ dir = up;
28
+ }
29
+ }
30
+
31
+ function readProjectLogin(projectId, home = os.homedir()) {
32
+ try {
33
+ const c = JSON.parse(fs.readFileSync(path.join(projectHome(projectId, home), ".qatools"), "utf8"));
34
+ return c && typeof c.apiKey === "string" && c.apiKey ? c : null;
35
+ } catch { return null; }
36
+ }
37
+
38
+ // Which login a qatools process should use:
39
+ // { use: "own" } — the person's own (~/.qatools) as before
40
+ // { use: "project", creds } — Claude, in a marked repo, with the project's own login
41
+ // { use: "refuse", message } — Claude in a marked repo without its own login: never the person's
42
+ // An explicit QATOOLS_API_KEY always wins (scheduled runs, CI).
43
+ function chooseLogin({ env = process.env, cwd = process.cwd(), home = os.homedir() } = {}) {
44
+ if (env.QATOOLS_API_KEY) return { use: "own" };
45
+ if (env.CLAUDECODE !== "1") return { use: "own" };
46
+ const marker = findProjectMarker(cwd);
47
+ if (!marker) return { use: "own" };
48
+ const creds = readProjectLogin(marker.projectId, home);
49
+ if (creds) return { use: "project", creds, marker };
50
+ return {
51
+ use: "refuse",
52
+ message: `This repo belongs to the qa-tools project ${marker.projectName || marker.projectId}, and Claude works there with the project's own login — not the person's. ` +
53
+ `Ask the person to run, in their own terminal in this repo: qatools init --claude-login`,
54
+ };
55
+ }
56
+
57
+ function writeProjectLogin({ projectId, projectName, apiKey }, home = os.homedir()) {
58
+ const dir = projectHome(projectId, home);
59
+ fs.mkdirSync(dir, { recursive: true });
60
+ const file = path.join(dir, ".qatools");
61
+ fs.writeFileSync(file, JSON.stringify({ apiKey, projectId, projectName: projectName || "" }, null, 2), { mode: 0o600 });
62
+ return dir;
63
+ }
64
+
65
+ function writeMarker(repoRoot, { projectId, projectName }) {
66
+ const f = path.join(repoRoot, MARKER);
67
+ fs.mkdirSync(path.dirname(f), { recursive: true });
68
+ fs.writeFileSync(f, JSON.stringify({ projectId, projectName: projectName || "", note: "qa-tools project of this repo (no secret). Claude's login is in ~/.qatools-projects/<projectId>, outside the repo." }, null, 2) + "\n");
69
+ return f;
70
+ }
71
+
72
+ // The MCP server entry for Claude Code: the same qatools, with HOME pointing at the project-own login folder
73
+ function mcpServerConfig(projectId, { node = process.execPath, cli = path.join(__dirname, "qatools.js"), home = os.homedir() } = {}) {
74
+ const dir = projectHome(projectId, home);
75
+ return { type: "stdio", command: node, args: [cli, "mcp"], env: { HOME: dir, USERPROFILE: dir, QATOOLS_NO_UPDATE_CHECK: "1" } };
76
+ }
77
+
78
+ module.exports = { MARKER, projectHome, findProjectMarker, readProjectLogin, chooseLogin, writeProjectLogin, writeMarker, mcpServerConfig };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "qatools-cli",
3
- "version": "1.2.40",
3
+ "version": "1.2.42",
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",
@@ -13,6 +13,7 @@
13
13
  "files": [
14
14
  "qatools.js",
15
15
  "mcp-core.js",
16
+ "own-login.js",
16
17
  "impact.js",
17
18
  "context-sync.js",
18
19
  "hooks.js",
package/qatools.js CHANGED
@@ -61,7 +61,7 @@ they would have built themselves if they had infinite time.
61
61
 
62
62
  You work in qa-tools as Claude, with this project's own Claude key — never on the person's login. On their login everything you do is recorded as them (your claims would count as their independent verification), and you reach all their projects with their rights.
63
63
 
64
- When \`qatools\` says "No credentials", or \`qatools brief\` shows a person's email or another project, stop and guide the person, in their language, one step at a time:
64
+ When \`qatools\` says "No credentials" or that the repo needs Claude's own login, or \`qatools brief\` shows a person's email or another project, stop and guide the person, in their language. The simple way: the project's owner opens their own terminal (not Claude Code — there it would count as you) in this repo and runs \`qatools init --claude-login\` (Claude must be switched on for the project in qa-tools). Then they restart Claude Code. For a scheduled run that needs the key in a file, one step at a time:
65
65
 
66
66
  1. In qa-tools: the project → Members → **Claude AI Integration** → **New key** (or **Generate key**) → **Copy**. A project has one Claude key and a new one replaces the old: if another session or scheduled run on this computer uses it, say so first.
67
67
  2. Save it from the clipboard, so the key is never typed or shown — Windows PowerShell: \`(Get-Clipboard).Trim() | Set-Content -NoNewline -Encoding ascii C:/qatools-loop/<project>-key.txt\`; macOS: \`mkdir -p ~/.qatools-keys && pbpaste > ~/.qatools-keys/<project>\`.
@@ -70,6 +70,17 @@ When \`qatools\` says "No credentials", or \`qatools brief\` shows a person's em
70
70
 
71
71
  Never ask for the key in the chat, never print or \`cat\` the file, never put it in the repo. Use it only as an environment variable (\`$env:QATOOLS_API_KEY = (Get-Content <file> -Raw).Trim()\`), or log a project-own home folder in with it for the MCP server (\`$env:HOME = <folder>; qatools login --api-key (Get-Content <file> -Raw).Trim()\`) and point the repo's MCP config at that folder. Then \`qatools brief\` must show the project and Claude.
72
72
 
73
+ ## Keeping qa-tools current
74
+
75
+ When the brief, a \`qatools\` command or the MCP server says qatools-cli or this repo's qa-tools skills are out of date, upgrade yourself — the person should not have to tell you:
76
+
77
+ 1. \`npm install -g qatools-cli@latest\`
78
+ 2. \`qatools init\` in the repo (updates .claude/skills and the hooks; with the repo's own Claude login it changes nothing else).
79
+ 3. Commit only the updated .claude files (chore: qa-tools skills <version>), following the repo's branch rules.
80
+ 4. Tell the person in one line: "Upgraded qatools-cli to <version>."
81
+
82
+ Never upgrade in an unattended run (nobody at the keyboard, e.g. a scheduled loop run): it must not change versions mid-run. Mention it in the run's summary instead.
83
+
73
84
  That standard rules out:
74
85
  - Guessing when verification is possible
75
86
  - "Looks right" without numbers
@@ -627,7 +638,7 @@ async function latestPublishedVersion() {
627
638
  const file = path.join(process.env.HOME || process.env.USERPROFILE || ".", UPDATE_CHECK_FILE);
628
639
  try {
629
640
  const c = JSON.parse(fs.readFileSync(file, "utf8"));
630
- if (c.latest && Date.now() - c.checkedAt < 24 * 3600 * 1000) return c.latest;
641
+ if (c.latest && Date.now() - c.checkedAt < 3600 * 1000) return c.latest; // cli.self-upgrade: a new version is noticed within the hour
631
642
  } catch {}
632
643
  try {
633
644
  const ctrl = new AbortController();
@@ -685,7 +696,12 @@ const functions = getFunctions(app);
685
696
  let envKeyProject = null;
686
697
 
687
698
  // Load credentials from ~/.qatools or env vars
699
+ // cli.claude-own-login: Claude (CLAUDECODE=1) in a repo marked with its project uses that project's own login,
700
+ // and refuses rather than fall back to the person's
688
701
  function getCredentials() {
702
+ const chosen = require("./own-login").chooseLogin();
703
+ if (chosen.use === "refuse") { console.error(chosen.message); process.exit(1); }
704
+ if (chosen.use === "project") return envKeyProject ? { ...chosen.creds, ...envKeyProject } : chosen.creds;
689
705
  const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
690
706
  let creds = null;
691
707
  if (fs.existsSync(configPath)) {
@@ -1563,8 +1579,9 @@ program
1563
1579
  }
1564
1580
  } catch {}
1565
1581
  const { renderBrief } = require("./brief");
1582
+ const warnings = await staleWarnings().catch(() => []); // cli.self-upgrade: the session sees it first thing
1566
1583
  console.log(renderBrief({ projectName: creds?.projectName || "", requirements, agenda: agendaRes?.agenda || null,
1567
- requests: reqsRes?.requests || [], branch, main, branchKeys }));
1584
+ requests: reqsRes?.requests || [], branch, main, branchKeys, warnings }));
1568
1585
  process.exit(0);
1569
1586
  } catch (e) {
1570
1587
  quietExit("Failed: " + e.message);
@@ -3384,14 +3401,83 @@ program
3384
3401
  process.exit(0);
3385
3402
  });
3386
3403
 
3404
+ // cli.claude-own-login: the owner gives Claude its own login for the repo's project — the key is never shown
3405
+ async function setupClaudeLogin(options) {
3406
+ const own = require("./own-login");
3407
+ if (process.env.CLAUDECODE === "1") {
3408
+ console.error("Run this yourself, in your own terminal: qatools init --claude-login. Claude does not create its own key.");
3409
+ process.exit(1);
3410
+ }
3411
+ if (process.env.QATOOLS_API_KEY) { console.error("QATOOLS_API_KEY is set — this needs your own login. Open a terminal without it."); process.exit(1); }
3412
+ let repoRoot = process.cwd();
3413
+ try { repoRoot = String(require("child_process").execFileSync("git", ["rev-parse", "--show-toplevel"], { stdio: ["ignore", "pipe", "ignore"] })).trim() || repoRoot; } catch {}
3414
+ repoRoot = path.resolve(repoRoot);
3415
+ await authenticate(options, { asMember: true }); // the person's own login
3416
+ const { projects } = (await httpsCallable(functions, "listProjects")({})).data;
3417
+ const marker = own.findProjectMarker(repoRoot);
3418
+ const projectId = options.project || marker?.projectId || getCredentials()?.projectId;
3419
+ const project = projects.find(p => p.id === projectId);
3420
+ if (!project) {
3421
+ console.error(`Which project? Pass --project <id>. Yours: ${projects.map(p => `${p.name} (${p.id})`).join(", ")}`);
3422
+ process.exit(1);
3423
+ }
3424
+ // A key only works while Claude is switched on for the project — that is the owner's decision, in the web app
3425
+ if (!project.claudeEnabled) {
3426
+ console.error(`Claude is not switched on for "${project.name}". In qa-tools: ${project.name} → Members → Claude AI Integration → switch it on. Then run this again.`);
3427
+ process.exit(1);
3428
+ }
3429
+ // A working login already there is reused — no new key
3430
+ let reused = false;
3431
+ const existing = own.readProjectLogin(project.id);
3432
+ if (existing) {
3433
+ try {
3434
+ const r = await (await fetch("https://us-central1-qatools-app.cloudfunctions.net/authenticateWithApiKey", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ data: { apiKey: existing.apiKey } }) })).json();
3435
+ reused = r.result?.projectId === project.id;
3436
+ } catch {}
3437
+ }
3438
+ if (!reused) {
3439
+ if (!options.yes) {
3440
+ const rl = require("readline").createInterface({ input: process.stdin, output: process.stdout });
3441
+ const answer = await new Promise(r => rl.question(`Create Claude's own key for "${project.name}"? A project has one Claude key: anything still using the current one (another computer, a scheduled run, a key file) stops working. [y/N] `, r));
3442
+ rl.close();
3443
+ if (!/^(y|yes|j|ja)$/i.test(String(answer).trim())) { console.log("Nothing changed."); process.exit(0); }
3444
+ }
3445
+ let key;
3446
+ try { key = (await httpsCallable(functions, "generateClaudeApiKey")({ projectId: project.id, scope: "full" })).data.key; }
3447
+ catch (e) {
3448
+ console.error(/owner/i.test(e.message) ? `Only the project's owner creates Claude's key. Ask them to run qatools init --claude-login in this repo.` : `Could not create the key: ${e.message}`);
3449
+ process.exit(1);
3450
+ }
3451
+ own.writeProjectLogin({ projectId: project.id, projectName: project.name, apiKey: key });
3452
+ }
3453
+ const markerFile = own.writeMarker(repoRoot, { projectId: project.id, projectName: project.name });
3454
+ // Claude Code's qatools MCP server for this repo (local scope: Claude Code's own settings, not the repo)
3455
+ const cfg = own.mcpServerConfig(project.id);
3456
+ const q = (s) => (/[\s"&|<>^]/.test(s) ? `"${s}"` : s);
3457
+ const envArgs = Object.entries(cfg.env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
3458
+ const sh = (args) => require("child_process").spawnSync("claude", args.map(q), { cwd: repoRoot, shell: true, encoding: "utf8" });
3459
+ sh(["mcp", "remove", "qatools", "--scope", "local"]);
3460
+ // the name first: -e takes several values and would swallow it
3461
+ const added = sh(["mcp", "add", "qatools", "--scope", "local", ...envArgs, "--", cfg.command, ...cfg.args]);
3462
+ console.log(reused ? `Claude's own login for ${project.name} was already set up — kept it.` : `Claude's own key for ${project.name} is created and kept in ${own.projectHome(project.id)} (outside the repo, never shown).`);
3463
+ console.log(`This repo is marked as ${project.name}: ${path.relative(repoRoot, markerFile)} — commit it (no secret in it).`);
3464
+ if (added.status === 0) console.log("Claude Code's qatools server for this repo now uses Claude's own login. Restart Claude Code (or reload the window).");
3465
+ else console.log(`Could not register the MCP server with Claude Code (${(added.stderr || added.error?.message || "claude not found").trim().split("\n")[0]}). Run in this repo:\n claude mcp add qatools --scope local ${envArgs.map(q).join(" ")} --${q(cfg.command)} ${cfg.args.map(q).join(" ")}`);
3466
+ console.log("From now on, when Claude runs qatools here it works as Claude for this project; when you do, it is you.");
3467
+ }
3468
+
3387
3469
  program
3388
3470
  .command("init")
3389
3471
  .description("One command to set up everything: login + skills + sync + agenda. Just run: qatools init --api-key <key>")
3390
3472
  .option("-k, --api-key <key>", "Claude API key (from QA-Tools → Members → Claude AI Integration)")
3473
+ .option("--claude-login", "Give Claude its own login for this repo's project (the owner runs it once, signed in as themselves): creates the project's Claude key, keeps it outside the repo and never shows it")
3474
+ .option("--project <id>", "With --claude-login: the project (default: the repo's marker, else your default project)")
3475
+ .option("-y, --yes", "With --claude-login: do not ask before replacing the project's Claude key")
3391
3476
  .option("-e, --email <email>", "Login email")
3392
3477
  .option("-p, --password <password>", "Login password")
3393
3478
  .action(async (options) => {
3394
3479
  const cwd = process.cwd();
3480
+ if (options.claudeLogin) { await setupClaudeLogin(options); process.exit(0); }
3395
3481
 
3396
3482
  // Step 0: Login if api-key provided and not already logged in
3397
3483
  const existingCreds = getCredentials();
@@ -4462,7 +4548,7 @@ program
4462
4548
  });
4463
4549
 
4464
4550
  program.hook("preAction", async (_root, cmd) => {
4465
- if (cmd.name() === "mcp") return; // the MCP server reports through instructions and get_agenda
4551
+ if (cmd.name() === "mcp" || cmd.name() === "brief") return; // the MCP server reports through instructions and get_agenda, the brief in its own text
4466
4552
  for (const w of await staleWarnings({ skipSkills: cmd.name() === "init" })) console.error(`⚠ ${w}`);
4467
4553
  });
4468
4554