qatools-cli 1.1.5 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qatools-cli",
-  "version": "1.1.5",
+  "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);
   });