gemstack-ai 1.4.0 → 2.0.0

package/src/lib/spec-merge.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * Spec Conflict & Merge Engine (Gemstack 2.0 Sprint C)
+ * Detects contract and test ID collisions between branches/specs offline.
+ */
+
+const { extractContractsBlock } = require('./contracts');
+const { extractTestMatrixBlock } = require('./test-matrix');
+
+/**
+ * Normalizes input which can be markdown string or parsed object.
+ * @param {string|object} specInput 
+ * @returns {{ contracts: Array, tests: Array, requirements: Array }}
+ */
+function normalizeSpecRepresentation(specInput) {
+  if (typeof specInput === 'object' && specInput !== null) {
+    return {
+      contracts: Array.isArray(specInput.contracts) ? specInput.contracts : [],
+      tests: Array.isArray(specInput.tests) ? specInput.tests : [],
+      requirements: Array.isArray(specInput.requirements) ? specInput.requirements : []
+    };
+  }
+
+  if (typeof specInput === 'string') {
+    const contractsRes = extractContractsBlock(specInput);
+    const contracts = !contractsRes.isLegacy ? contractsRes.contracts : [];
+
+    const matrixRes = extractTestMatrixBlock(specInput);
+    const tests = !matrixRes.isLegacy ? matrixRes.matrix : [];
+
+    return {
+      contracts,
+      tests,
+      requirements: []
+    };
+  }
+
+  return { contracts: [], tests: [], requirements: [] };
+}
+
+/**
+ * Detects conflicts between two specifications.
+ * @param {string|object} specA - Base or local spec
+ * @param {string|object} specB - Incoming or remote spec
+ * @returns {{ valid: boolean, conflicts: Array<{ type: string, id: string, reason: string, details?: any }> }}
+ */
+function detectSpecConflicts(specA, specB) {
+  const repA = normalizeSpecRepresentation(specA);
+  const repB = normalizeSpecRepresentation(specB);
+
+  const conflicts = [];
+
+  // 1. Detect Contract Collisions
+  const contractsMapA = new Map(repA.contracts.map(c => [c.id, c]));
+  for (const cB of repB.contracts) {
+    if (contractsMapA.has(cB.id)) {
+      const cA = contractsMapA.get(cB.id);
+
+      // Check type collision
+      if (cA.type !== cB.type) {
+        conflicts.push({
+          type: 'CONTRACT_COLLISION',
+          id: cB.id,
+          reason: `Contract "${cB.id}" has conflicting types: "${cA.type}" vs "${cB.type}".`
+        });
+        continue;
+      }
+
+      // Check value collision based on type
+      if (cA.type === 'BOOLEAN_INVARIANT' && cA.value !== cB.value) {
+        conflicts.push({
+          type: 'CONTRACT_COLLISION',
+          id: cB.id,
+          reason: `Contract "${cB.id}" has conflicting boolean values: ${cA.value} vs ${cB.value}.`
+        });
+      } else if (cA.type === 'ENUM_SET') {
+        const setA = new Set(cA.values || []);
+        const setB = new Set(cB.values || []);
+        // If values differ materially and neither is empty
+        const diffA = [...setA].filter(x => !setB.has(x));
+        const diffB = [...setB].filter(x => !setA.has(x));
+        if (diffA.length > 0 || diffB.length > 0) {
+          conflicts.push({
+            type: 'CONTRACT_COLLISION',
+            id: cB.id,
+            reason: `Contract ENUM_SET "${cB.id}" has divergent enum values.`
+          });
+        }
+      } else {
+        // Generic deep check
+        if (JSON.stringify(cA) !== JSON.stringify(cB)) {
+          conflicts.push({
+            type: 'CONTRACT_COLLISION',
+            id: cB.id,
+            reason: `Contract "${cB.id}" has incompatible configuration definitions.`
+          });
+        }
+      }
+    }
+  }
+
+  // 2. Detect Test ID Collisions with divergent criteria
+  const testsMapA = new Map(repA.tests.map(t => [t.id, t]));
+  for (const tB of repB.tests) {
+    if (testsMapA.has(tB.id)) {
+      const tA = testsMapA.get(tB.id);
+      if (
+        tA.category !== tB.category ||
+        tA.layer !== tB.layer ||
+        tA.gate !== tB.gate ||
+        tA.description !== tB.description ||
+        tA.pass_criteria !== tB.pass_criteria
+      ) {
+        conflicts.push({
+          type: 'DUPLICATE_TEST_ID',
+          id: tB.id,
+          reason: `Canonical test ID "${tB.id}" is declared in both specs with divergent definitions.`
+        });
+      }
+    }
+  }
+
+  return {
+    valid: conflicts.length === 0,
+    conflicts
+  };
+}
+
+/**
+ * Merges two specifications if no conflicts exist.
+ * @param {string|object} specA 
+ * @param {string|object} specB 
+ * @returns {object} Merged representation
+ */
+function mergeSpecs(specA, specB) {
+  const conflictReport = detectSpecConflicts(specA, specB);
+  if (!conflictReport.valid) {
+    const err = new Error(`Conflictos detectados al fusionar especificaciones: ${conflictReport.conflicts.map(c => `${c.type} (${c.id}): ${c.reason}`).join('; ')}`);
+    err.code = 'SPEC_MERGE_CONFLICT';
+    err.conflicts = conflictReport.conflicts;
+    throw err;
+  }
+
+  const repA = normalizeSpecRepresentation(specA);
+  const repB = normalizeSpecRepresentation(specB);
+
+  // Merge contracts (union by ID)
+  const contractsMap = new Map();
+  for (const c of repA.contracts) contractsMap.set(c.id, c);
+  for (const c of repB.contracts) contractsMap.set(c.id, c);
+
+  // Merge tests (union by ID)
+  const testsMap = new Map();
+  for (const t of repA.tests) testsMap.set(t.id, t);
+  for (const t of repB.tests) testsMap.set(t.id, t);
+
+  return {
+    contracts: Array.from(contractsMap.values()),
+    tests: Array.from(testsMap.values()),
+    requirements: [...repA.requirements, ...repB.requirements]
+  };
+}
+
+module.exports = {
+  detectSpecConflicts,
+  mergeSpecs
+};

package/src/lib/swarm.js

@@ -234,7 +234,7 @@ function planSwarmWaves(tasks) {
     const nextRemaining = [];
 
     for (const task of remaining) {
-      const taskWrites = (task.write_set || []).map(normalizePath);
+      const taskWrites = (task.write_set || []).map(p => normalizePath(p));
       let collides = false;
 
       for (const p of taskWrites) {
@@ -283,7 +283,7 @@ function validateWritePartitions(wave) {
   const claimedPaths = new Map(); // path -> task_id
 
   for (const t of tasks) {
-    const writes = (t.write_set || []).map(normalizePath);
+    const writes = (t.write_set || []).map(p => normalizePath(p));
     for (const p of writes) {
       if (claimedPaths.has(p)) {
         const otherTaskId = claimedPaths.get(p);

package/src/lib/visual-qa.js

@@ -10,8 +10,9 @@
 const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
-const { normalizePath } = require('./hasher');
+const { normalizePath, hashFile } = require('./hasher');
 const { createFinding } = require('./findings');
+const fssafe = require('./filesystem-safe');
 
 const VQA_SCHEMA_VERSION = '1.0.0';
 
@@ -266,14 +267,42 @@ function validateBaselineIntegrity(scenario, targetDir) {
 }
 
 /**
- * Compares live visual evidence against canonical baseline.
+ * Sanitizes and masks sensitive input fields and tokens before visual capture persistence.
+ *
+ * @param {string} content - HTML or DOM text
+ * @returns {string} Sanitized content with sensitive data masked
+ */
+function maskSensitiveFieldsBeforeCapture(content) {
+  if (!content || typeof content !== 'string') return content;
+  let masked = content;
+
+  // 1. Password input values
+  masked = masked.replace(/(<input\b[^>]*\btype\s*=\s*["']?password["']?[^>]*\bvalue\s*=\s*["'])([^"']*)(["'])/gi, '$1[MASKED_PASSWORD]$3');
+  masked = masked.replace(/(<input\b[^>]*\bvalue\s*=\s*["'])([^"']*)(["'][^>]*\btype\s*=\s*["']?password["']?[^>]*>)/gi, '$1[MASKED_PASSWORD]$3');
+
+  // 2. Sensitive ids or names (password, token, secret, key, credit_card, card)
+  masked = masked.replace(/(<input\b[^>]*(?:\bid|\bname)\s*=\s*["']?[^"']*(?:password|token|secret|key|credit_card|card)[^"']*["']?[^>]*\bvalue\s*=\s*["'])([^"']*)(["'])/gi, '$1[MASKED_SENSITIVE]$3');
+  masked = masked.replace(/(<input\b[^>]*\bvalue\s*=\s*["'])([^"']*)(["'][^>]*(?:\bid|\bname)\s*=\s*["']?[^"']*(?:password|token|secret|key|credit_card|card)[^"']*["']?[^>]*>)/gi, '$1[MASKED_SENSITIVE]$3');
+
+  // 3. API Keys and Tokens in attributes or text
+  masked = masked.replace(/sk-(?:live_|proj-)?[a-zA-Z0-9_-]{10,}/g, '[MASKED_KEY]');
+
+  // 4. Credit card numbers (13-19 consecutive digits or grouped with spaces/dashes)
+  masked = masked.replace(/\b(?:\d{4}[ -]?){3,4}\d{1,4}\b/g, '[MASKED_CARD]');
+
+  return masked;
+}
+
+/**
+ * Compares live visual evidence against canonical baseline with honest disk recomputation.
  *
  * @param {object} scenario - Scenario definition
  * @param {object} evidence - Submitted evidence object
  * @param {string} targetDir - Repository target directory
+ * @param {object} [options={}] - Additional options (e.g. diffAdapter)
  * @returns {{ status: string, passed: boolean, diff_percentage: number, findings: Array<object> }}
  */
-function compareVisualEvidence(scenario, evidence, targetDir) {
+function compareVisualEvidence(scenario, evidence, targetDir, options = {}) {
   const findings = [];
   const baseline = scenario.baseline;
 
@@ -299,8 +328,81 @@ function compareVisualEvidence(scenario, evidence, targetDir) {
     return { status: 'BASELINE_MISSING', passed: false, diff_percentage: 1.0, findings };
   }
 
-  // Fast-path: SHA-256 match
-  if (evidence.image_sha256 && baseline.image_sha256 && evidence.image_sha256 === baseline.image_sha256) {
+  let effectiveLiveHash = evidence.image_sha256;
+  let effectiveBaselineHash = baseline.image_sha256;
+
+  // Recompute hashes directly from disk files if targetDir and paths are available
+  if (targetDir) {
+    if (baseline.image_path) {
+      try {
+        const absBaselinePath = fssafe.resolveSafeStrict(targetDir, baseline.image_path);
+        if (fs.existsSync(absBaselinePath)) {
+          const diskBaselineHash = hashFile(absBaselinePath);
+          if (baseline.image_sha256 && diskBaselineHash !== baseline.image_sha256) {
+            findings.push(createFinding({
+              code: 'VQA_BASELINE_TAMPERED',
+              contractId: 'baseline-explicit-update-only',
+              phase: 'visual-qa',
+              location: baseline.image_path,
+              details: `Baseline image "${baseline.image_path}" was modified on disk. Recorded: ${baseline.image_sha256}, Actual: ${diskBaselineHash}.`
+            }));
+            return { status: 'BASELINE_TAMPERED', passed: false, diff_percentage: 1.0, findings };
+          }
+          effectiveBaselineHash = diskBaselineHash;
+        }
+      } catch (err) {
+        findings.push(createFinding({
+          code: 'VQA_BASELINE_TAMPERED',
+          contractId: 'baseline-explicit-update-only',
+          phase: 'visual-qa',
+          location: baseline.image_path,
+          details: `Error validating baseline path: ${err.message}`
+        }));
+        return { status: 'BASELINE_TAMPERED', passed: false, diff_percentage: 1.0, findings };
+      }
+    }
+
+    const livePathCandidate = evidence.live_screenshot_path || (evidence.image_path && fs.existsSync(fssafe.resolveSafe(targetDir, evidence.image_path)) ? evidence.image_path : null);
+    if (livePathCandidate) {
+      try {
+        const absLivePath = fssafe.resolveSafeStrict(targetDir, livePathCandidate);
+        if (!fs.existsSync(absLivePath)) {
+          findings.push(createFinding({
+            code: 'VQA_IMAGE_NOT_FOUND',
+            contractId: 'visual-evidence-subordinate',
+            phase: 'visual-qa',
+            location: scenario.scenario_id,
+            details: `Live screenshot file not found: ${livePathCandidate}`
+          }));
+          return { status: 'EVIDENCE_MISSING', passed: false, diff_percentage: 1.0, findings };
+        }
+        const diskLiveHash = hashFile(absLivePath);
+        if (evidence.image_sha256 && evidence.image_sha256 !== diskLiveHash) {
+          findings.push(createFinding({
+            code: 'VQA_EVIDENCE_HASH_MISMATCH',
+            contractId: 'visual-evidence-subordinate',
+            phase: 'visual-qa',
+            location: scenario.scenario_id,
+            details: `Submitted evidence image_sha256 (${evidence.image_sha256}) does not match disk file hash (${diskLiveHash}).`
+          }));
+          return { status: 'EVIDENCE_HASH_MISMATCH', passed: false, diff_percentage: 1.0, findings };
+        }
+        effectiveLiveHash = diskLiveHash;
+      } catch (err) {
+        findings.push(createFinding({
+          code: 'VQA_IMAGE_NOT_FOUND',
+          contractId: 'visual-evidence-subordinate',
+          phase: 'visual-qa',
+          location: scenario.scenario_id,
+          details: `Error validating live screenshot path: ${err.message}`
+        }));
+        return { status: 'EVIDENCE_MISSING', passed: false, diff_percentage: 1.0, findings };
+      }
+    }
+  }
+
+  // Fast-path: SHA-256 match from verified disk hashes
+  if (effectiveLiveHash && effectiveBaselineHash && effectiveLiveHash === effectiveBaselineHash) {
     return {
       status: 'PASS',
       passed: true,
@@ -309,11 +411,52 @@ function compareVisualEvidence(scenario, evidence, targetDir) {
     };
   }
 
-  // Evaluate tolerances
+  // Evaluate tolerances and real diff adapter
   const maxDiff = (scenario.tolerances && scenario.tolerances.max_diff_percentage !== undefined)
     ? scenario.tolerances.max_diff_percentage
     : 0.00;
 
+  const diffAdapter = (options && options.diffAdapter) || (evidence && evidence.diffAdapter);
+
+  if (diffAdapter && typeof diffAdapter.computeDiff === 'function') {
+    let baselineBuf = null;
+    let liveBuf = null;
+    if (targetDir && baseline.image_path) {
+      try { baselineBuf = fs.readFileSync(fssafe.resolveSafeStrict(targetDir, baseline.image_path)); } catch {}
+    }
+    const liveRel = evidence.live_screenshot_path || evidence.image_path;
+    if (targetDir && liveRel) {
+      try { liveBuf = fs.readFileSync(fssafe.resolveSafeStrict(targetDir, liveRel)); } catch {}
+    }
+
+    const diffResult = diffAdapter.computeDiff(baselineBuf, liveBuf, scenario.tolerances);
+    const observedDiff = typeof diffResult.diff_percentage === 'number' ? diffResult.diff_percentage : 0.0;
+
+    if (observedDiff > maxDiff) {
+      findings.push(createFinding({
+        code: 'VQA_VISUAL_REGRESSION',
+        contractId: 'visual-evidence-subordinate',
+        phase: 'visual-qa',
+        location: scenario.scenario_id,
+        details: `Visual regression on "${scenario.scenario_id}": observed diff ${observedDiff} exceeds maximum allowed ${maxDiff}.`
+      }));
+      return {
+        status: 'VISUAL_REGRESSION',
+        passed: false,
+        diff_percentage: observedDiff,
+        findings
+      };
+    }
+
+    return {
+      status: 'PASS',
+      passed: true,
+      diff_percentage: observedDiff,
+      findings: []
+    };
+  }
+
+  // If no diff adapter is provided:
   const observedDiff = typeof evidence.diff_percentage === 'number' ? evidence.diff_percentage : 0.05;
 
   if (observedDiff > maxDiff) {
@@ -332,11 +475,20 @@ function compareVisualEvidence(scenario, evidence, targetDir) {
     };
   }
 
+  // When live screenshot differs from baseline and caller claims low diff without adapter: FAIL-CLOSED UNVERIFIED
+  findings.push(createFinding({
+    code: 'VQA_DIFF_ENGINE_UNAVAILABLE',
+    contractId: 'visual-evidence-subordinate',
+    phase: 'visual-qa',
+    location: scenario.scenario_id,
+    details: `Visual deviation detected on "${scenario.scenario_id}" but no diff engine adapter is available. Status UNVERIFIED.`
+  }));
+
   return {
-    status: 'PASS',
-    passed: true,
+    status: 'UNVERIFIED',
+    passed: false,
     diff_percentage: observedDiff,
-    findings: []
+    findings
   };
 }
 
@@ -492,6 +644,7 @@ module.exports = {
   validateViewport,
   validateEnvironmentMetadata,
   applySelectorMasks,
+  maskSensitiveFieldsBeforeCapture,
   validateBaselineIntegrity,
   compareVisualEvidence,
   promoteVisualBaseline,

package/template/.agents/rules/03-gemstack-security.md

@@ -1,7 +1,7 @@
-# Gemstack Security Core (Military-Grade Shielding)
+# Gemstack Security Core (Architecture & Security Gates)
 
 ## Propósito
-Esta es la Ley de "Seguridad por Diseño". Todo código escrito, planificado o revisado por la IA bajo el marco Gemstack DEBE adherirse a estos principios de blindaje, independientemente del stack tecnológico utilizado. El objetivo es mitigar el 99% de las vulnerabilidades comunes (OWASP) desde el momento de la concepción del código.
+Esta es la Ley de "Seguridad por Diseño". Todo código escrito, planificado o revisado por la IA bajo el marco Gemstack DEBE adherirse a estos principios de blindaje, independientemente del stack tecnológico utilizado. El objetivo es establecer controles sistemáticos y verificables frente a vulnerabilidades comunes (OWASP Top 10) desde el momento de la concepción del código.
 
 ## 1. Cero Exposición de Credenciales (Zero Trust Secrets)
 - **Regla Estricta:** JAMÁS hardcodees contraseñas, llaves de API, secrets de Webhooks o URIs de bases de datos en el código fuente.

package/.github/workflows/main-ci.yml

@@ -1,32 +0,0 @@
-name: Main CI
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  test:
-    name: Full CI
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        node-version: [18.x, 20.x]
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - name: Install Dependencies
-        run: npm install
-      - name: Run Native Tests
-        run: npm test
-      - name: Run CI Suite
-        run: npm run ci:all
-      - name: Run Demo Smoke
-        run: npm run ci:demo
-      - name: Validate Package Build
-        run: npm run pack:dry

package/.github/workflows/pr-ci.yml

@@ -1,31 +0,0 @@
-name: PR CI
-
-on:
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  test:
-    name: Quick CI
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x]
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - name: Install Dependencies
-        run: npm install
-      - name: Run Native Tests
-        run: npm test
-      - name: Run CI Suite
-        run: npm run ci:all
-      - name: Run Demo Smoke
-        run: npm run ci:demo
-      - name: Validate Package Build
-        run: npm run pack:dry

package/.github/workflows/publish.yml

@@ -1,52 +0,0 @@
-name: Publish Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  contents: write # Requerido para crear GitHub Releases
-
-jobs:
-  publish:
-    name: Publish to NPM and GitHub Releases
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install Dependencies
-        run: npm ci || npm install
-
-      - name: Security Gate - Run CI All
-        run: npm run ci:all
-
-      - name: Pack Package
-        run: npm pack
-        id: pack
-
-      - name: Publish to NPM
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Create GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Obtener el nombre del archivo tarball generado por npm pack
-          TARBALL=$(ls gemstack-*.tgz)
-          
-          # Crear el Release oficial de GitHub usando el CLI nativo 'gh'
-          gh release create ${{ github.ref_name }} \
-            --title "Release ${{ github.ref_name }}" \
-            --notes-file RELEASE_NOTES.md \
-            $TARBALL

package/.github/workflows/release-readiness.yml

@@ -1,43 +0,0 @@
-name: Release Readiness
-
-on:
-  workflow_dispatch:
-
-jobs:
-  validate-and-pack:
-    name: Validate and Pack
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-      - name: Install Dependencies
-        run: npm install
-      - name: Run Native Tests
-        run: npm test
-      - name: Run CI Suite
-        run: npm run ci:all
-      - name: Run Demo Smoke
-        run: npm run ci:demo
-      - name: Pack NPM Tarball
-        run: npm pack
-      - name: Test Tarball in Dummy Project
-        run: |
-          mkdir ../gemstack-dummy
-          cd ../gemstack-dummy
-          npm init -y
-          npm install ../Gemstack/gemstack-*.tgz
-          npx gemstack --help
-          npx gemstack init --dry-run
-          npx gemstack init --yes
-          npx gemstack doctor
-          npx gemstack update --dry-run
-      - name: Upload NPM Tarball
-        uses: actions/upload-artifact@v4
-        with:
-          name: gemstack-npm-tarball
-          path: gemstack-*.tgz
-          if-no-files-found: error