gemstack-ai 1.1.2 → 1.3.0

package/src/lib/provider-registry.js

@@ -0,0 +1,265 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { createFinding } = require('./findings');
+
+const VALID_ENV_TIERS = ['test', 'ci', 'development', 'staging', 'production'];
+const PROVIDER_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const REMOTE_URL_PATTERN = /^https?:\/\//i;
+
+/**
+ * Resolves the deterministic environment tier.
+ *
+ * @param {object} [options={}]
+ * @param {string} [options.environment]
+ * @param {object} [options.env=process.env]
+ * @returns {string} One of: 'test', 'ci', 'development', 'staging', 'production'
+ */
+function resolveEnvironmentTier(options = {}) {
+  const env = options.env || process.env;
+
+  if (options.environment && VALID_ENV_TIERS.includes(options.environment)) {
+    return options.environment;
+  }
+
+  if (env.GEMSTACK_ENV && VALID_ENV_TIERS.includes(env.GEMSTACK_ENV)) {
+    return env.GEMSTACK_ENV;
+  }
+
+  // Detect CI first
+  if (env.CI === 'true' || env.CI === '1' || env.CONTINUOUS_INTEGRATION === 'true') {
+    return 'ci';
+  }
+
+  // Detect test runner
+  if (env.NODE_ENV === 'test' || typeof global.it === 'function' || typeof global.test === 'function' || process.argv.includes('--test')) {
+    return 'test';
+  }
+
+  return 'development';
+}
+
+/**
+ * Validates whether commercial providers are permitted in a given environment tier.
+ *
+ * @param {string} envTier
+ * @param {object} [options={}]
+ * @param {boolean} [options.allowBillable=false]
+ * @param {object} [options.ciWaiver=null]
+ * @returns {{ allowed: boolean, reasonCode: string, message: string }}
+ */
+function checkEnvironmentCommercialPolicy(envTier, options = {}) {
+  if (envTier === 'test') {
+    return {
+      allowed: false,
+      reasonCode: 'ENV_COMMERCIAL_DENIED',
+      message: 'Commercial provider invocation is strictly denied in test environment.'
+    };
+  }
+
+  if (envTier === 'ci') {
+    if (options.ciWaiver && options.ciWaiver.signed === true && options.ciWaiver.expires_at > Date.now()) {
+      return {
+        allowed: true,
+        reasonCode: 'CI_WAIVER_ACCEPTED',
+        message: 'Commercial invocation permitted in CI via explicit signed waiver.'
+      };
+    }
+    return {
+      allowed: false,
+      reasonCode: 'ENV_COMMERCIAL_DENIED',
+      message: 'Commercial provider invocation is denied in CI environment without explicit signed waiver.'
+    };
+  }
+
+  if (envTier === 'development') {
+    if (!options.allowBillable) {
+      return {
+        allowed: false,
+        reasonCode: 'BILLABLE_ACTION_UNAUTHORIZED',
+        message: 'Commercial provider actions in development require explicit authorization (--allow-billable).'
+      };
+    }
+    return {
+      allowed: true,
+      reasonCode: 'DEV_AUTHORIZED',
+      message: 'Commercial execution authorized for development session.'
+    };
+  }
+
+  // staging / production
+  return {
+    allowed: true,
+    reasonCode: 'PRODUCTION_ALLOWED',
+    message: 'Commercial execution permitted under managed environment.'
+  };
+}
+
+/**
+ * Validates integrity of a MOCK provider configuration to prevent network escape.
+ *
+ * @param {object} providerConfig
+ * @returns {{ valid: boolean, reasonCode: string|null, message: string|null }}
+ */
+function validateMockIntegrity(providerConfig) {
+  if (!providerConfig || typeof providerConfig !== 'object') {
+    return {
+      valid: false,
+      reasonCode: 'MOCK_PROVIDER_ESCAPE_VIOLATION',
+      message: 'Mock provider configuration must be a valid object.'
+    };
+  }
+
+  if (providerConfig.type !== 'MOCK') {
+    return {
+      valid: false,
+      reasonCode: 'MOCK_PROVIDER_ESCAPE_VIOLATION',
+      message: 'Provider is not declared with type "MOCK".'
+    };
+  }
+
+  // Scan for remote endpoints, urls, or external host configurations
+  const forbiddenFields = ['url', 'endpoint', 'baseUrl', 'base_url', 'host', 'remoteUrl', 'remote_url'];
+  for (const field of forbiddenFields) {
+    if (typeof providerConfig[field] === 'string' && providerConfig[field].trim()) {
+      const val = providerConfig[field].trim();
+      if (REMOTE_URL_PATTERN.test(val) || val.includes('://') || (!val.includes('localhost') && !val.includes('127.0.0.1') && val.includes('.'))) {
+        return {
+          valid: false,
+          reasonCode: 'MOCK_PROVIDER_ESCAPE_VIOLATION',
+          message: 'Mock provider declared forbidden remote endpoint at field "' + field + '": ' + val
+        };
+      }
+    }
+  }
+
+  // Scan nested capabilities for remote endpoint overrides
+  if (providerConfig.capabilities && typeof providerConfig.capabilities === 'object') {
+    for (const [capId, cap] of Object.entries(providerConfig.capabilities)) {
+      if (cap && typeof cap === 'object') {
+        for (const field of forbiddenFields) {
+          if (typeof cap[field] === 'string' && cap[field].trim()) {
+            return {
+              valid: false,
+              reasonCode: 'MOCK_PROVIDER_ESCAPE_VIOLATION',
+              message: 'Mock capability "' + capId + '" declared forbidden remote endpoint at "' + field + '".'
+            };
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: true,
+    reasonCode: null,
+    message: null
+  };
+}
+
+/**
+ * Creates an in-memory ProviderRegistry instance.
+ *
+ * @param {object} providersMap
+ * @returns {object} ProviderRegistry
+ */
+function createProviderRegistry(providersMap = {}) {
+  const normalizedProviders = new Map();
+
+  for (const [rawId, config] of Object.entries(providersMap)) {
+    const id = rawId.toLowerCase().trim();
+    if (!PROVIDER_ID_REGEX.test(id)) {
+      throw new Error('Invalid provider ID format: "' + rawId + '". Must match slug pattern: ' + PROVIDER_ID_REGEX.toString());
+    }
+
+    const type = (config.type || 'COMMERCIAL').toUpperCase();
+    const capabilities = new Map();
+
+    if (config.capabilities) {
+      if (Array.isArray(config.capabilities)) {
+        for (const cap of config.capabilities) {
+          capabilities.set(cap, { id: cap });
+        }
+      } else if (typeof config.capabilities === 'object') {
+        for (const [capId, capVal] of Object.entries(config.capabilities)) {
+          capabilities.set(capId, capVal);
+        }
+      }
+    }
+
+    normalizedProviders.set(id, {
+      ...config,
+      id,
+      type,
+      capabilities
+    });
+  }
+
+  return {
+    hasProvider(providerId) {
+      if (typeof providerId !== 'string') return false;
+      return normalizedProviders.has(providerId.toLowerCase().trim());
+    },
+
+    getProvider(providerId) {
+      if (typeof providerId !== 'string') return null;
+      return normalizedProviders.get(providerId.toLowerCase().trim()) || null;
+    },
+
+    hasCapability(providerId, capabilityId) {
+      const p = this.getProvider(providerId);
+      if (!p) return false;
+      return p.capabilities.has(capabilityId);
+    },
+
+    getCapability(providerId, capabilityId) {
+      const p = this.getProvider(providerId);
+      if (!p) return null;
+      return p.capabilities.get(capabilityId) || null;
+    },
+
+    listProviders() {
+      return Array.from(normalizedProviders.values());
+    }
+  };
+}
+
+/**
+ * Loads provider registry from repository artifacts or ledger.
+ *
+ * @param {string} rootPath
+ * @param {string} [featureDir='']
+ * @returns {object} ProviderRegistry
+ */
+function loadProviderRegistry(rootPath, featureDir = '') {
+  const candidatePaths = [
+    path.join(rootPath, featureDir, 'cost-ledger.json'),
+    path.join(rootPath, 'cost-ledger.json'),
+    path.join(rootPath, '.gemstack/cost-ledger.json'),
+    path.join(rootPath, '.gemstack/providers.json')
+  ];
+
+  for (const p of candidatePaths) {
+    if (fs.existsSync(p)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+        if (raw.providers && typeof raw.providers === 'object') {
+          return createProviderRegistry(raw.providers);
+        }
+      } catch (e) {
+        // Fall through to next candidate
+      }
+    }
+  }
+
+  return createProviderRegistry({});
+}
+
+module.exports = {
+  VALID_ENV_TIERS,
+  PROVIDER_ID_REGEX,
+  resolveEnvironmentTier,
+  checkEnvironmentCommercialPolicy,
+  validateMockIntegrity,
+  createProviderRegistry,
+  loadProviderRegistry
+};

package/src/lib/runner-adapters.js

@@ -0,0 +1,347 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { writeJsonAtomic } = require('./state');
+
+/**
+ * Spawns node:test runner safely with explicit argv and shell: false.
+ *
+ * @param {string} rootPath
+ * @param {Array<string>} testFiles
+ * @param {object} options
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string, durationMs: number }>}
+ */
+function executeNodeTestRunner(rootPath, testFiles, options = {}) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    const args = ['--test', '--test-reporter=tap', ...(testFiles || [])];
+
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.NODE_TEST_CONTEXT;
+    delete cleanEnv.NODE_TEST_WORKER_ID;
+
+    const child = spawn(process.execPath, args, {
+      cwd: rootPath,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: cleanEnv
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+
+    child.on('error', (err) => {
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr: err.message,
+        durationMs: Date.now() - startTime
+      });
+    });
+
+    child.on('close', (exitCode) => {
+      resolve({
+        exitCode: exitCode === null ? 1 : exitCode,
+        stdout,
+        stderr,
+        durationMs: Date.now() - startTime
+      });
+    });
+  });
+}
+
+/**
+ * Parses node:test TAP output to extract physical counts and test events.
+ *
+ * @param {string} tapOutput
+ * @returns {{ physicalTotal: number, passed: number, failed: number, skipped: number, todo: number, cancelled: number, tests: Array<object> }}
+ */
+function parseNodeTestTap(tapOutput) {
+  const lines = (tapOutput || '').split('\n');
+  const tests = [];
+  const suites = [];
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  let todo = 0;
+  let cancelled = 0;
+
+  const idRegex = /\b(TEST-[A-Z0-9]+-[A-Z0-9]+)\b/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // TAP test line format: ok 1 - title # duration_ms
+    // or: not ok 2 - title # duration_ms
+    if (trimmed.startsWith('ok ') || trimmed.startsWith('not ok ')) {
+      const isNotOk = trimmed.startsWith('not ok ');
+      const rest = isNotOk ? trimmed.slice(7) : trimmed.slice(3);
+
+      // Remove test number: "1 - title..."
+      const numMatch = rest.match(/^\d+\s*-\s*(.*)/);
+      const titleAndDirectives = numMatch ? numMatch[1] : rest;
+
+      // Lookahead in YAML diagnostic block for "type: 'suite'" vs "type: 'test'"
+      let eventType = null;
+      let durationMs = 0;
+
+      for (let j = i + 1; j < Math.min(i + 15, lines.length); j++) {
+        const nextTrimmed = lines[j].trim();
+        if (nextTrimmed === '...') break;
+        if (nextTrimmed.startsWith('ok ') || nextTrimmed.startsWith('not ok ')) break;
+
+        const typeMatch = nextTrimmed.match(/^type:\s*['"]?([a-zA-Z0-9_-]+)['"]?/i);
+        if (typeMatch) {
+          eventType = typeMatch[1].toLowerCase();
+        }
+
+        const durMatch = nextTrimmed.match(/^duration_ms:\s*([\d.]+)/i);
+        if (durMatch) {
+          durationMs = parseFloat(durMatch[1]);
+        }
+      }
+
+      // Check inline duration if not in YAML
+      if (!durationMs) {
+        const durMatchInline = titleAndDirectives.match(/duration_ms\s*[:=]\s*([\d.]+)/i) ||
+                               titleAndDirectives.match(/time=([\d.]+)ms/i);
+        if (durMatchInline) durationMs = parseFloat(durMatchInline[1]);
+      }
+
+      // If explicit suite container event in TAP, classify as SUITE and exclude from physical tests
+      if (eventType === 'suite') {
+        suites.push({
+          kind: 'SUITE',
+          title: titleAndDirectives.split('#')[0].trim(),
+          durationMs
+        });
+        continue;
+      }
+
+      let rawOutcome = isNotOk ? 'FAIL' : 'PASS';
+
+      if (/#\s*SKIP\b/i.test(titleAndDirectives)) {
+        rawOutcome = 'SKIP';
+      } else if (/#\s*TODO\b/i.test(titleAndDirectives)) {
+        rawOutcome = 'TODO';
+      } else if (/#\s*CANCELLED\b/i.test(titleAndDirectives)) {
+        rawOutcome = 'CANCELLED';
+      }
+
+      const idMatch = titleAndDirectives.match(idRegex);
+      const canonicalId = idMatch ? idMatch[1] : null;
+
+      if (rawOutcome === 'PASS') passed++;
+      else if (rawOutcome === 'FAIL') failed++;
+      else if (rawOutcome === 'SKIP') skipped++;
+      else if (rawOutcome === 'TODO') todo++;
+      else if (rawOutcome === 'CANCELLED') cancelled++;
+
+      tests.push({
+        kind: 'TEST',
+        id: canonicalId,
+        title: titleAndDirectives.split('#')[0].trim(),
+        rawOutcome,
+        durationMs,
+        isSupporting: canonicalId === null
+      });
+    }
+  }
+
+  const physicalTotal = passed + failed + skipped + todo + cancelled;
+
+  return {
+    physicalTotal,
+    passed,
+    failed,
+    skipped,
+    todo,
+    cancelled,
+    tests,
+    suites
+  };
+}
+
+/**
+ * Reconciles canonical acceptance requirements with runner execution traces.
+ *
+ * @param {Array<object>} canonicalMatrix
+ * @param {Array<object>} planBindings
+ * @param {Array<object>} executedEvents
+ * @returns {object}
+ */
+function reconcileTestRun(canonicalMatrix, planBindings, executedEvents) {
+  const boundCanonicalIds = new Set((planBindings || []).map(b => b.test_id));
+  const expectedRequired = (canonicalMatrix || []).filter(m => m.gate === 'REQUIRED');
+  const validCanonicalIds = new Set((canonicalMatrix || []).map(m => m.id));
+
+  const executedCanonical = [];
+  const executedSupporting = [];
+  const executedIdCounts = {};
+
+  for (const ev of (executedEvents || [])) {
+    if (ev.id) {
+      executedCanonical.push(ev);
+      executedIdCounts[ev.id] = (executedIdCounts[ev.id] || 0) + 1;
+    } else {
+      executedSupporting.push(ev);
+    }
+  }
+
+  // 1. Check duplicate physical execution identities
+  const duplicates = Object.keys(executedIdCounts).filter(id => executedIdCounts[id] > 1);
+
+  // 2. Check orphans (physical test claimed canonical ID absent from SPEC)
+  const orphans = Object.keys(executedIdCounts).filter(id => !validCanonicalIds.has(id));
+
+  // 3. Check missing vs not executed
+  const executedIdSet = new Set(Object.keys(executedIdCounts));
+  const missing = [];
+  const notExecuted = [];
+
+  for (const req of expectedRequired) {
+    if (!boundCanonicalIds.has(req.id)) {
+      missing.push(req.id);
+    } else if (!executedIdSet.has(req.id)) {
+      notExecuted.push(req.id);
+    }
+  }
+
+  // 4. Check phantoms (phantom test: claimed executed/pass but absent from runner events)
+  const phantoms = [];
+
+  // 5. Arithmetic equation validation
+  const canonicalCount = executedCanonical.length;
+  const supportingCount = executedSupporting.length;
+  const totalPhysical = executedEvents.length;
+
+  const mathValid = (canonicalCount + supportingCount === totalPhysical);
+
+  return {
+    mathValid,
+    totalPhysical,
+    canonicalCount,
+    supportingCount,
+    duplicates,
+    orphans,
+    missing,
+    notExecuted,
+    phantoms
+  };
+}
+
+/**
+ * Executes a PACKAGE_SCRIPT gate safely without shell: true.
+ *
+ * @param {string} rootPath
+ * @param {object} gateConfig
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
+ */
+function executePackageScriptGate(rootPath, gateConfig) {
+  return new Promise((resolve) => {
+    const pkgPath = path.join(rootPath, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      const err = new Error('package.json not found for PACKAGE_SCRIPT gate');
+      err.code = 'REQUIRED_GATE_MISSING';
+      return resolve({ exitCode: 1, stdout: '', stderr: err.message, error: err });
+    }
+
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch (e) {
+      const err = new Error('Failed to parse package.json: ' + e.message);
+      err.code = 'REQUIRED_GATE_MISSING';
+      return resolve({ exitCode: 1, stdout: '', stderr: err.message, error: err });
+    }
+
+    if (!pkg.scripts || !pkg.scripts[gateConfig.script]) {
+      const err = new Error('Script "' + gateConfig.script + '" not found in package.json');
+      err.code = 'REQUIRED_GATE_MISSING';
+      return resolve({ exitCode: 1, stdout: '', stderr: err.message, error: err });
+    }
+
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.NODE_TEST_CONTEXT;
+    delete cleanEnv.NODE_TEST_WORKER_ID;
+
+    let execBinary = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    let execArgs = ['run', gateConfig.script];
+
+    // On Windows, node.js spawn('npm.cmd', ..., { shell: false }) triggers EINVAL in node 22+ unless .cmd is spawned via cmd /c or direct npm-cli.js
+    if (process.platform === 'win32') {
+      const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+      if (fs.existsSync(npmCli)) {
+        execBinary = process.execPath;
+        execArgs = [npmCli, 'run', gateConfig.script];
+      }
+    }
+
+    const child = spawn(execBinary, execArgs, {
+      cwd: rootPath,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: cleanEnv
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+
+    child.on('error', (err) => {
+      resolve({ exitCode: 1, stdout, stderr: err.message, error: err });
+    });
+
+    child.on('close', (exitCode) => {
+      resolve({ exitCode: exitCode === null ? 1 : exitCode, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * Assembles and atomically writes the feature-local closure.json manifest.
+ *
+ * @param {string} targetDir
+ * @param {object} manifestData
+ * @returns {object} Written manifest
+ */
+function generateClosureManifest(targetDir, manifestData) {
+  const closurePath = path.join(targetDir, 'closure.json');
+
+  const manifest = {
+    schema: 'gemstack-closure',
+    version: 1,
+    feature: manifestData.feature,
+    generated_at: manifestData.generated_at || new Date().toISOString(),
+    status: manifestData.status,
+    closure_context: manifestData.closure_context,
+    acceptance_signature: manifestData.acceptance_signature,
+    canonical_summary: manifestData.canonical_summary,
+    physical_summary: manifestData.physical_summary,
+    reconciliation: manifestData.reconciliation,
+    task_traceability_summary: manifestData.task_traceability_summary,
+    required_gates: manifestData.required_gates || {},
+    supplemental_gates: manifestData.supplemental_gates || {},
+    exceptions: manifestData.exceptions || [],
+    evidence_sources: manifestData.evidence_sources || [],
+    blockers: manifestData.blockers || [],
+    warnings: manifestData.warnings || []
+  };
+
+  writeJsonAtomic(closurePath, manifest);
+  return manifest;
+}
+
+module.exports = {
+  executeNodeTestRunner,
+  parseNodeTestTap,
+  reconcileTestRun,
+  executePackageScriptGate,
+  generateClosureManifest
+};