qa360 2.2.6 → 2.2.7

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to QA360 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+---
+
+## ⚠️ BROKEN VERSIONS - DO NOT USE
+
+| Version | Status | Issue | Fixed In |
+|---------|--------|-------|----------|
+| **2.2.4** | 🔴 BROKEN | Published without CI check (CI was failing) | 2.2.6 |
+| **2.2.5** | 🔴 BROKEN | Published without bundle script - missing `cli/dist/core/` | 2.2.6 |
+
+**Use version 2.2.6 or later instead.**
+
+---
+
+## [2.2.6] - 2025-01-18
+
+### Fixed
+- **Critical bundle fix**: Re-ran bundle script correctly before publication
+  - `cli/dist/core/` now contains the bundled core engine
+  - Imports correctly use `../core/index.js` instead of `qa360-core`
+  - Package installation now works correctly
+- **Recovery**: This version fixes the broken 2.2.4 and 2.2.5 releases
+
+### Added
+- **npm Publication Workflow section** in README with mandatory checklist
+- Documented fatal mistakes from 2.2.4 and 2.2.5 to prevent recurrence
+
+---
+
 ## Versioning Convention
 
 QA360 uses **Node.js-style versioning** (Major.Minor.Patch).

package/README.md

@@ -215,6 +215,85 @@ QA360 Core is developed in structured phases:
 - **Phase 8**: ✅ TUI & Dashboard (COMPLETE)
 - **Phase 9**: ⏳ Parallel CI → consolidated proof
 
+## 🚢 npm Publication Workflow (CRITICAL)
+
+> **⚠️ WARNING: Publishing broken packages damages user trust permanently.**
+
+### Mandatory Pre-Publication Checklist
+
+**NEVER skip these steps - versions 2.2.4 and 2.2.5 were broken due to skipping these:**
+
+1. ✅ **CI MUST be green** on both `develop` AND `main`
+2. ✅ **Run bundle script**: `cd cli && bash scripts/bundle-for-npm.sh`
+3. ✅ **Test with npm pack**: `npm pack && tar -tzf qa360-*.tgz | grep "cli/dist/core/index.js"`
+4. ✅ **Test installation**: `cd /tmp && npm install -g ./qa360-*.tgz && qa360 --version`
+5. ✅ **Get EXPLICIT authorization** from maintainer before publishing
+6. ✅ **Publish from MAIN branch only** - NEVER from `develop`
+
+### The Fatal Mistakes (DO NOT REPEAT)
+
+| Version | Mistake | Result |
+|---------|---------|--------|
+| **2.2.4** | Published without CI check | CI was failing - broken package |
+| **2.2.5** | Published without bundle script | Missing `cli/dist/core/` - completely broken |
+| **2.2.6** | Followed full checklist | ✅ Working package |
+
+### Correct Publication Workflow
+
+```bash
+# 1. Verify CI is green
+gh run list --branch develop --limit 1
+gh run list --branch main --limit 1
+
+# 2. Merge develop to main
+git checkout main
+git merge develop --no-ff
+git push origin main
+
+# 3. Wait for CI to pass on main
+gh run watch --branch main
+
+# 4. CREATE THE BUNDLE (THIS IS CRITICAL)
+cd cli
+bash scripts/bundle-for-npm.sh
+cd ..
+
+# 5. Verify bundle was created
+ls -la cli/dist/core/index.js  # Must exist
+grep "from '../core/index.js'" cli/dist/commands/ai.js  # Must show this, NOT qa360-core
+
+# 6. Test the package locally
+npm pack
+tar -tzf qa360-*.tgz | grep "cli/dist/core/index.js"  # Must exist
+cd /tmp && npm install -g /path/to/qa360-*.tgz && qa360 --version
+
+# 7. ONLY AFTER ALL TESTS PASS: Get authorization, then publish
+npm version patch  # or minor/major
+npm publish --access public
+git push origin main --tags
+
+# 8. ALWAYS return to develop
+git checkout develop
+```
+
+### Why the Bundle Script Is Critical
+
+The bundle script (`cli/scripts/bundle-for-npm.sh`) does:
+1. Copies `core/src/*` into `cli/src/core/`
+2. Changes imports from `'qa360-core'` to `'../core/index.js'`
+3. Builds TypeScript → `cli/dist/`
+4. **Result**: `cli/dist/core/` contains the bundled core engine
+
+**Without this step**: The CLI imports `'qa360-core'` which doesn't exist in the npm package → **COMPLETELY BROKEN**
+
+### Recovery from Broken Publication
+
+If a broken version is published:
+1. **Fix the issue** on `develop`
+2. **Follow the FULL checklist** above
+3. **Publish a patch version** (e.g., 2.2.5 → 2.2.6)
+4. **Add a warning** in CHANGELOG about broken versions
+
 ## 🛠️ Technology Stack
 
 - **Runtime**: Node.js 18+ with TypeScript 5+

package/cli/dist/core/ai/ollama-provider.js

@@ -32,16 +32,28 @@ export class OllamaProvider {
     }
     async isAvailable() {
         try {
-            // Use timeout with AbortSignal - wrap for compatibility
+            // Use a longer timeout (15 seconds) to accommodate slower systems
+            // Ollama can take time to respond, especially on first run or with many models
             const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 5000);
+            const timeoutId = setTimeout(() => controller.abort(), 15000);
             const response = await fetch(`${this.baseUrl}/api/tags`, {
                 signal: controller.signal,
             });
             clearTimeout(timeoutId);
             return response.ok;
         }
-        catch {
+        catch (error) {
+            // Log the error for debugging (will be visible in verbose mode)
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    // Timeout - Ollama is slow to respond
+                    console.debug(`[Ollama] Connection to ${this.baseUrl} timed out after 15s`);
+                }
+                else {
+                    // Other error (ECONNREFUSED, ENOTFOUND, etc.)
+                    console.debug(`[Ollama] Connection error: ${error.message}`);
+                }
+            }
             return false;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qa360",
-  "version": "2.2.6",
+  "version": "2.2.7",
   "description": "Transform software testing into verifiable, signed, and traceable proofs",
   "type": "module",
   "packageManager": "pnpm@9.12.2",