qatools-cli 1.1.4 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qatools-cli",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "CLI for QA Tools — requirements, epics, sprints, sessions, App Context sync, project agenda. The companion to qa-tools.com.",
   "bin": {
     "qatools": "./qatools.js"

package/qatools.js

@@ -684,6 +684,7 @@ program
   .option("--project <id>", "Target project ID (overrides default)")
   .option("-o, --output <path>", "Path to file to update (auto: .claude/CLAUDE.md if it exists, else CLAUDE.md)")
   .option("--check", "Exit 1 if file is out of sync (does not modify)")
+  .option("--dry-run", "Show what would change without writing the file")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
@@ -739,6 +740,49 @@ program
       }
     }
 
+    if (options.dryRun) {
+      if (existing === updated) {
+        console.log(`✓ ${options.output} already in sync — nothing would change.`);
+        process.exit(0);
+      }
+      const beginIdxNow = existing.indexOf(beginMarker);
+      if (beginIdxNow < 0) {
+        console.log(`Would CREATE qatools-context block in ${options.output}:`);
+        console.log(`  + ${md.split('\n').length} lines (${md.length} chars)`);
+        console.log(`  Block markers: ${beginMarker} ... ${endMarker}`);
+        console.log(``);
+        console.log(`First 10 lines of new content:`);
+        md.split('\n').slice(0, 10).forEach(l => console.log(`  + ${l}`));
+        process.exit(0);
+      }
+      // Compute a simple line-level diff between old block and new block
+      const oldEnd = existing.indexOf(endMarker);
+      const oldBlockLines = existing.slice(beginIdxNow, oldEnd + endMarker.length).split('\n');
+      const newBlockLines = block.split('\n');
+      console.log(`Would UPDATE qatools-context block in ${options.output}:`);
+      console.log(`  Old: ${oldBlockLines.length} lines`);
+      console.log(`  New: ${newBlockLines.length} lines`);
+      console.log(``);
+      // Show added/removed lines (simple set diff — ignores reordering)
+      const oldSet = new Set(oldBlockLines.map(l => l.trim()).filter(Boolean));
+      const newSet = new Set(newBlockLines.map(l => l.trim()).filter(Boolean));
+      const added = [...newSet].filter(l => !oldSet.has(l));
+      const removed = [...oldSet].filter(l => !newSet.has(l));
+      if (removed.length) {
+        console.log(`  ${removed.length} line(s) removed:`);
+        removed.slice(0, 15).forEach(l => console.log(`    - ${l.substring(0, 100)}`));
+        if (removed.length > 15) console.log(`    ... and ${removed.length - 15} more`);
+      }
+      if (added.length) {
+        console.log(`  ${added.length} line(s) added:`);
+        added.slice(0, 15).forEach(l => console.log(`    + ${l.substring(0, 100)}`));
+        if (added.length > 15) console.log(`    ... and ${added.length - 15} more`);
+      }
+      console.log(``);
+      console.log(`Run without --dry-run to write the changes.`);
+      process.exit(0);
+    }
+
     if (existing === updated) {
       console.log(`✓ ${options.output} already in sync (no changes)`);
     } else {
@@ -1359,9 +1403,74 @@ program
     process.exit(0);
   });
 
+program
+  .command("context-template")
+  .description("Print an empty App Context JSON template with all fields and example values. Pipe to a file, edit, then context-set.")
+  .option("-o, --output <path>", "Write to file instead of stdout")
+  .action((options) => {
+    const template = {
+      name: "Your project name",
+      purpose: "One sentence: what does this app do and why does it exist?",
+      domainObjects: [
+        "User",
+        "Order",
+        "Product"
+      ],
+      actors: [
+        "End user",
+        "Admin",
+        "External system"
+      ],
+      stack: [
+        { layer: "Frontend", technology: "React", version: "18", notes: "with TypeScript" },
+        { layer: "Backend", technology: "Node.js", version: "20", notes: "Express" },
+        { layer: "Database", technology: "PostgreSQL", version: "16", notes: "" }
+      ],
+      architecture: "Short description of how the system is structured. Where does data flow? What's the main pattern?",
+      security: [
+        "All endpoints require authentication",
+        "Data is isolated per tenant via tenantId column"
+      ],
+      aiRules: [
+        "Build from requirements — never from backlog items",
+        "Evidence-first: cite specific code, test output, or error message",
+        "Never guess — say 'I'm unsure' if evidence is missing",
+        "Acceptance criteria in Given/When/Then on the project's language (sv: Givet/När/Då, en: Given/When/Then) — never mix"
+      ],
+      constraints: [
+        "Hard constraint #1 (e.g. must run offline)",
+        "Hard constraint #2 (e.g. no third-party AI calls)"
+      ],
+      conventions: [
+        { area: "Naming", rule: "camelCase for variables, PascalCase for components" },
+        { area: "Errors", rule: "Always throw with a Result type, never silent fail" }
+      ],
+      environments: [
+        { name: "Production", url: "https://app.example.com", notes: "" },
+        { name: "Staging", url: "https://staging.example.com", notes: "" }
+      ],
+      integrations: [
+        { name: "Stripe", purpose: "Payments" },
+        { name: "SendGrid", purpose: "Transactional email" }
+      ],
+      sections: [
+        { title: "Custom section title", content: "Free-text content for anything that doesn't fit the structured fields above. Use this for project-specific docs, runbooks, glossaries, etc." }
+      ]
+    };
+    const json = JSON.stringify(template, null, 2);
+    if (options.output) {
+      fs.writeFileSync(path.resolve(options.output), json);
+      console.error(`Template written to ${options.output}`);
+      console.error(`Edit it, then upload with: qatools context-set -f ${options.output}`);
+    } else {
+      console.log(json);
+    }
+    process.exit(0);
+  });
+
 program
   .command("context-set")
-  .description("Upload App Context from JSON file")
+  .description("Upload App Context from JSON file. Run 'qatools context-template' to see the expected schema.")
   .requiredOption("-f, --file <path>", "Path to App Context JSON file")
   .option("--project <id>", "Target project ID (overrides default; requires access to that project)")
   .option("-e, --email <email>", "Login email")
@@ -1375,6 +1484,13 @@ program
     const saveCtx = httpsCallable(functions, "saveAppContext");
     const result = await saveCtx({ projectId, context: data });
     console.log(`App Context saved (${result.data.id}) — project ${projectId}`);
+    if (result.data.warnings && result.data.warnings.length > 0) {
+      console.error(``);
+      console.error(`⚠ Schema warnings (${result.data.warnings.length}):`);
+      for (const w of result.data.warnings) console.error(`   ${w}`);
+      console.error(``);
+      console.error(`   These fields were saved but may be ignored. Run 'qatools context-template' to see the schema.`);
+    }
     process.exit(0);
   });
 
@@ -1632,6 +1748,83 @@ program
 
     // 2. Write skills files
     const skills = {
+      "qa-purpose.md": `---
+description: Read this BEFORE anything else. The purpose of qa-tools and what it expects from you as AI.
+---
+
+# Why qa-tools exists
+
+qa-tools exists for one reason: to let anyone build production-quality apps with AI that follow their own rules — as if they had built it themselves, just faster.
+
+Not "demo quality, fast". Not "good enough, fast". **The user's own quality bar, faster.**
+
+## What this means for you (the AI)
+
+You are not a coding assistant. You are a substitute. The user is delegating
+construction of their app to you, and they expect what comes back to be what
+they would have built themselves if they had infinite time.
+
+That standard rules out:
+- Guessing when verification is possible
+- "Looks right" without numbers
+- "User will test it" handoffs of responsibility
+- Shortcuts the user themselves wouldn't take
+- Pattern-matched code from training data when the project has its own rules
+
+## The chain
+
+\`\`\`
+App Context (the user's rules: design, security, AI rules, constraints)
+        ↓
+Epics (capabilities the user wants)
+        ↓
+Requirements (Given/When/Then — the user's spec, testable)
+        ↓
+Code (you build, must trace to requirement)
+        ↓
+Tests (generated from REQUIREMENTS, not from code)
+        ↓
+Backlog (signals when chain breaks: AVV / GAP / DEF / IMP)
+        ↓
+Fix (against the requirement, with --evidence)
+        ↓
+Requirement marked tested
+\`\`\`
+
+Every link is enforceable. The CLI refuses status changes without evidence.
+The skills refuse vague claims. The model refuses circular fixes (backlog →
+backlog without going through requirements).
+
+## Your starting move
+
+Before doing ANYTHING in this project:
+1. Run \`qatools context\` — read the App Context. This is the user's rule book.
+2. Run \`qatools epics\` — see what capabilities exist.
+3. Run \`qatools next\` — see what's actually on the agenda.
+
+If App Context is empty, the project hasn't been set up yet. Help the user
+draft one before building anything else. **Without App Context you have no
+basis for being a substitute** — you're just guessing what their rules are.
+
+## When you're tempted to skip the chain
+
+You will be tempted. The user will be impatient. The bug will look obvious.
+You will think "I'll just fix it and they can verify".
+
+That is exactly the failure mode qa-tools was built to prevent. The substitute
+that "just fixes things" is the substitute that drifts away from what the
+user actually wanted, one shortcut at a time.
+
+When you feel that temptation, stop. Ask: would the user themselves skip this
+step if they were doing it manually? If no, you can't either.
+
+## Cross-reference
+
+- qa-loop.md — the mechanics of the loop
+- qa-evidence-first.md — the core principle (cite, don't guess)
+- qa-numerical-verification.md — for algorithmic bugs
+- qa-developer.md — implementation guidance
+`,
       "qa-loop.md": `---
 description: Overview of the QA-Tools delivery loop — from requirement to verified release. Read this first.
 ---
@@ -1653,6 +1846,22 @@ Requirement → Build → Test → Backlog → Fix → Verify
 5. **AI analyzes and fixes** — AI identifies root cause: is it the code or the requirement? Fixes code or suggests requirement adjustment.
 6. **Retest verifies** — The loop closes only when the requirement is verified.
 
+## What this means for you (the AI)
+
+Each arrow in the loop is a rule on what you can and cannot do:
+
+**Requirement → Build** means: you don't build until there's an approved requirement. Period. If the user asks you to fix something without a requirement, your first response is "can you formulate what the system should do as a requirement?" — not "sure, I'll fix it".
+
+**Build → Test** means: the code is not done until there's a test that verifies it meets the requirement. "I compiled it" is not done. "I ran the file and it didn't crash" is not done.
+
+**Test → Backlog** means: when the test fails, that's a signal to you that either the requirement or the code is wrong. You don't guess which — you investigate. The backlog item is the *observation*, not the diagnosis.
+
+**Backlog → Fix** means: the fix comes from the requirement, not from the backlog item. The backlog item is the symptom. The requirement is what you build against. If you fix the symptom without going back to the requirement, you're patching, not building.
+
+**Fix → Verify** means: you don't mark tested without --evidence. The CLI refuses status changes without it. That's not bureaucracy — it's the line between claiming and verifying. If you cannot articulate the verification, you have not verified.
+
+If any of these feels like friction, that is the system working as intended. The friction is what keeps the chain unbroken.
+
 ## CLI quick reference
 
 \`\`\`bash
@@ -2064,7 +2273,8 @@ If the verification fails: do NOT mark tested. Go back to step 1, find the discr
     for (const [filename, content] of Object.entries(skills)) {
       fs.writeFileSync(path.join(skillsDir, filename), content);
     }
-    console.log("  ✓ qa-loop.md (start here)");
+    console.log("  ✓ qa-purpose.md (READ FIRST)");
+    console.log("  ✓ qa-loop.md");
     console.log("  ✓ qa-requirement-analyst.md");
     console.log("  ✓ qa-developer.md");
     console.log("  ✓ qa-test-generator.md");
@@ -2115,23 +2325,32 @@ If the verification fails: do NOT mark tested. Go back to step 1, find the discr
     const qaSection = `
 ## QA-Tools Integration
 
+This project uses qa-tools (https://qa-tools.com) for requirement-driven AI development. The purpose: build production-quality apps with AI that follow your own rules — as if you built it yourself, just faster. The AI is the builder; you are the requirements author and reviewer.
+
+**Read \`.claude/skills/qa-purpose.md\` before doing anything in this project.** It explains what qa-tools expects from the AI: not a coding assistant, a substitute for the developer.
+
 \`\`\`bash
 export QATOOLS_API_KEY=${apiKey || "<din-nyckel>"}
 \`\`\`
 
-### Kommandon
-- \`qatools requirements\` — lista krav
-- \`qatools backlog\` — lista backlog
-- \`qatools pending\` — väntande testsessioner
-- \`qatools read-session -s <id>\` — läs session
-- \`qatools upload-analysis -s <id> -f analysis.json\` — ladda upp analys
-- \`qatools requirement-create -f file.json\` — skapa krav
-- \`qatools template-upload -f file.json\` — ladda upp testprotokoll
-- \`qatools backlog-create -d "..." -t task\` — skapa ärende
-- \`qatools backlog-update -i <id> --status resolved\` — uppdatera
-
-### Roller (skills)
-Se \`.claude/skills/\` för instruktioner per roll.
+### Commands
+- \`qatools context\` — read the project's rule book (App Context)
+- \`qatools epics\` — list capabilities
+- \`qatools next\` — what's on the agenda right now
+- \`qatools requirements\` — list requirements
+- \`qatools backlog\` — list backlog signals
+- \`qatools pending\` — test sessions awaiting analysis
+- \`qatools read-session -s <id>\` — read session details
+- \`qatools upload-analysis -s <id> -f analysis.json\` — upload analysis
+- \`qatools requirement-create -f file.json\` — create requirements
+- \`qatools requirement-update -i <id> --status tested --evidence "..."\` — mark verified (evidence required)
+- \`qatools template-upload -f file.json\` — upload test template
+- \`qatools backlog-create -d "..." -t bug\` — create backlog item
+- \`qatools backlog-update -i <id> --status resolved --evidence "..."\` — mark resolved (evidence required)
+- \`qatools access show\` — view access model
+
+### Skills
+See \`.claude/skills/\` for role-specific instructions. Start with \`qa-purpose.md\`.
 `;
 
     if (fs.existsSync(claudeMdPath)) {
@@ -2147,8 +2366,41 @@ Se \`.claude/skills/\` för instruktioner per roll.
       console.log("\n✓ Created CLAUDE.md with QA-Tools section");
     }
 
-    console.log("\n🎉 QA-Tools initialized! Claude is ready.");
-    if (!apiKey) console.log("\n⚠ No API key set. Add it to CLAUDE.md: export QATOOLS_API_KEY=<key>");
+    // 5. Final purpose-first banner — check App Context state and tell the AI/user what to do
+    let contextStateMessage = "";
+    try {
+      const creds = getCredentials();
+      if (creds?.projectId) {
+        const getCtx = httpsCallable(functions, "getAppContext");
+        const ctxResult = await getCtx({ projectId: creds.projectId });
+        const ctx = ctxResult.data.appContext;
+        if (!ctx || (!ctx.purpose && !(ctx.stack || []).length && !(ctx.aiRules || []).length)) {
+          contextStateMessage = "\n⚠ App Context is empty for this project.\n   Without it, the AI has no basis for substituting for you.\n   First step: open https://qa-tools.com and define App Context (purpose, stack, conventions, AI rules)\n   or upload a JSON via: qatools context-set -f context.json\n";
+        } else {
+          const lastSync = ctx.updatedAt?._seconds ? new Date(ctx.updatedAt._seconds * 1000).toISOString().split('T')[0] : 'unknown';
+          contextStateMessage = `\n✓ App Context loaded (last updated: ${lastSync})\n`;
+        }
+      }
+    } catch (e) {
+      // Best-effort — don't block init on this check
+    }
+
+    console.log(`
+🎉 QA-Tools initialized!
+
+⚠ READ THIS FIRST: .claude/skills/qa-purpose.md
+
+   qa-tools exists to let anyone build production-quality apps with AI
+   that follow their own rules — as if you built it yourself, just faster.
+   The AI is not an assistant. It is a substitute for the developer.
+   Read qa-purpose.md before doing anything else in this project.
+${contextStateMessage}
+Next steps for the AI in this project:
+  1. qatools context     — read the project's rule book
+  2. qatools epics       — see what capabilities exist
+  3. qatools next        — see what's on the agenda
+`);
+    if (!apiKey) console.log("⚠ No API key set. Add it to CLAUDE.md: export QATOOLS_API_KEY=<key>\n");
     process.exit(0);
   });