@veraxhq/verax 0.2.1 → 0.4.0

package/src/cli/util/project-discovery.js

@@ -33,6 +33,7 @@ export async function discoverProject(srcPath) {
   let packageJson = null;
   if (packageJsonPath && existsSync(packageJsonPath)) {
     try {
+  // @ts-expect-error - readFileSync with encoding returns string
       packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
     } catch (error) {
       packageJson = null;
@@ -64,6 +65,44 @@ export async function discoverProject(srcPath) {
   };
 }
 
+/**
+ * Synchronous project profile resolver used by zero-config helpers
+ */
+export function getProjectProfile(projectPath) {
+  const projectRoot = resolve(projectPath);
+  const packageJsonPath = findPackageJson(projectRoot);
+  const projectDir = packageJsonPath ? dirname(packageJsonPath) : projectRoot;
+
+  let packageJson = null;
+  if (packageJsonPath && existsSync(packageJsonPath)) {
+    try {
+  // @ts-expect-error - readFileSync with encoding returns string
+      packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    } catch {
+      packageJson = null;
+    }
+  }
+
+  const framework = detectFramework(projectDir, packageJson);
+  const router = detectRouter(framework, projectDir);
+  const packageManager = detectPackageManager(projectDir);
+  const scripts = {
+    dev: packageJson?.scripts?.dev || null,
+    build: packageJson?.scripts?.build || null,
+    start: packageJson?.scripts?.start || null,
+  };
+
+  return {
+    framework,
+    router,
+    sourceRoot: projectDir,
+    packageManager,
+    scripts,
+    detectedAt: new Date().toISOString(),
+    packageJsonPath,
+  };
+}
+
 /**
  * Find the nearest package.json by walking up directories
  */
@@ -295,3 +334,248 @@ export function extractPortFromScript(script) {
   
   return null;
 }
+
+/**
+ * Detect if running in CI environment (H5: Zero-Config)
+ */
+export function isCI() {
+  return !!(
+    process.env.CI ||
+    process.env.CONTINUOUS_INTEGRATION ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.CIRCLECI ||
+    process.env.TRAVIS ||
+    process.env.BUILDKITE
+  );
+}
+
+/**
+ * Check if a port is accessible via HTTP (H5: Zero-Config)
+ */
+export async function isPortAccessible(port, host = 'localhost', timeout = 3000) {
+  return new Promise(resolve => {
+    const _startTime = Date.now();
+    const timeoutId = setTimeout(() => {
+      resolve(false);
+    }, timeout);
+
+    try {
+      const http = require('http');
+      const req = http.get(
+        {
+          hostname: host,
+          port,
+          path: '/',
+          timeout: 1000,
+        },
+        () => {
+          clearTimeout(timeoutId);
+          resolve(true);
+        }
+      );
+
+      req.on('error', () => {
+        clearTimeout(timeoutId);
+        resolve(false);
+      });
+
+      req.on('timeout', () => {
+        clearTimeout(timeoutId);
+        req.destroy();
+        resolve(false);
+      });
+    } catch (e) {
+      clearTimeout(timeoutId);
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Infer URL from existing framework detection (H5: Zero-Config)
+ */
+export async function inferURL(projectPath, profile, preferredPort = null) {
+  const result = {
+    url: null,
+    port: preferredPort || 3000,
+    discovered: false,
+  };
+
+  // Extract port from scripts if available
+  const profile2 = profile || getProjectProfile(projectPath);
+  if (profile2?.scripts?.dev && !preferredPort) {
+    const portFromScript = extractPortFromScript(profile2.scripts.dev);
+    if (portFromScript) {
+      result.port = portFromScript;
+    }
+  }
+
+  // Try preferred port
+  if (await isPortAccessible(result.port, 'localhost', 1000)) {
+    result.url = `http://localhost:${result.port}`;
+    result.discovered = true;
+    return result;
+  }
+
+  // Try common ports
+  const commonPorts = [3000, 5173, 4200, 8080, 8000];
+  for (const port of commonPorts) {
+    if (await isPortAccessible(port, 'localhost', 1000)) {
+      result.url = `http://localhost:${port}`;
+      result.port = port;
+      result.discovered = true;
+      return result;
+    }
+  }
+
+  // No port found
+  return result;
+}
+
+/**
+ * Full zero-config setup (H5: Zero-Config)
+ * Returns: { url, discovery }
+ */
+export async function setupZeroConfig(projectPath, providedURL = null) {
+  const discovery = {
+    method: null,
+    framework: null,
+    serverAutoStarted: false,
+    details: {},
+  };
+
+  // If URL provided, use it immediately
+  if (providedURL) {
+    discovery.method = 'provided';
+    return {
+      url: providedURL,
+      discovery,
+    };
+  }
+
+  // Detect framework
+  const profile = getProjectProfile(projectPath);
+  discovery.framework = profile?.framework || 'unknown';
+
+  // Try to infer URL from existing ports
+  const inference = await inferURL(projectPath, profile);
+
+  if (inference.discovered) {
+    discovery.method = 'inferred';
+    discovery.details = {
+      port: inference.port,
+      framework: profile?.framework,
+    };
+    return {
+      url: inference.url,
+      discovery,
+    };
+  }
+
+  // Server not running and auto-start is disabled in CI
+  if (isCI()) {
+    throw new Error(
+      `No running server detected on port ${inference.port}. ` +
+        'In CI environment, use --url to specify server URL.'
+    );
+  }
+
+  // H5: Auto-start dev server (max 30s startup)
+  try {
+    const started = await autoStartDevServer(projectPath, profile, inference.port);
+    if (started.success) {
+      discovery.method = 'auto-started';
+      discovery.serverAutoStarted = true;
+      discovery.details = {
+        port: started.port,
+        framework: profile?.framework,
+        startupTime: started.startupTime,
+      };
+      return {
+        url: `http://localhost:${started.port}`,
+        discovery,
+      };
+    }
+  } catch (e) {
+    // Fall through to error
+  }
+
+  // Could not start server
+  throw new Error(
+    `No running server detected on port ${inference.port}. ` +
+      'Start your dev server or use --url to specify the server URL.'
+  );
+}
+
+/**
+ * H5: Auto-start development server
+ * Supports: Next.js, Vite, CRA, Vue, Svelte, Angular
+ * Max 30 second startup with automatic port detection
+ */
+export async function autoStartDevServer(projectPath, profile = null, preferredPort = 3000) {
+  const prof = profile || getProjectProfile(projectPath);
+  
+  if (!prof?.scripts?.dev) {
+    return { success: false, reason: 'no-dev-script' };
+  }
+
+  // Extract port from dev script
+  const port = extractPortFromScript(prof.scripts.dev) || preferredPort;
+
+  // Check if port is already accessible (server already running)
+  if (await isPortAccessible(port, 'localhost', 1000)) {
+    return { success: true, port, startupTime: 0 };
+  }
+
+  // Import required modules for spawning process
+  const { spawn } = await import('child_process');
+  const startTime = Date.now();
+  const MAX_STARTUP_TIME = 30 * 1000; // 30 seconds
+
+  return new Promise((resolve) => {
+    let resolved = false;
+
+    const process = spawn('npm', ['run', 'dev'], {
+      cwd: projectPath,
+      stdio: 'ignore',
+      detached: true,
+    });
+
+    // Detach the process so it doesn't keep this process alive
+    process.unref();
+
+    // Poll for port accessibility
+    const pollInterval = setInterval(async () => {
+      const elapsed = Date.now() - startTime;
+
+      if (elapsed > MAX_STARTUP_TIME) {
+        clearInterval(pollInterval);
+        if (!resolved) {
+          resolved = true;
+          resolve({ success: false, reason: 'startup-timeout', elapsed });
+        }
+        return;
+      }
+
+      if (await isPortAccessible(port, 'localhost', 1000)) {
+        clearInterval(pollInterval);
+        if (!resolved) {
+          resolved = true;
+          const startupTime = Date.now() - startTime;
+          resolve({ success: true, port, startupTime });
+        }
+      }
+    }, 500); // Check every 500ms
+
+    // Timeout safety
+    setTimeout(() => {
+      clearInterval(pollInterval);
+      if (!resolved) {
+        resolved = true;
+        resolve({ success: false, reason: 'startup-timeout', elapsed: MAX_STARTUP_TIME });
+      }
+    }, MAX_STARTUP_TIME + 1000);
+  });
+}
+

package/src/cli/util/project-writer.js

@@ -1,5 +1,6 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write project profile artifact
@@ -8,6 +9,7 @@ export function writeProjectJson(runPaths, projectProfile) {
   const projectJsonPath = resolve(runPaths.baseDir, 'project.json');
   
   const projectJson = {
+    contractVersion: ARTIFACT_REGISTRY.project.contractVersion,
     framework: projectProfile.framework,
     router: projectProfile.router,
     sourceRoot: projectProfile.sourceRoot,

package/src/cli/util/run-id.js

@@ -1,30 +1,26 @@
-import crypto from 'crypto';
+import { generateRunId as generateDeterministicRunId } from '../../verax/core/run-id.js';
 
-/**
- * Generate a run ID in format: <ISO_TIMESTAMP_UTC>_<6-8 char short hash>
- * Example: 2026-01-11T00-59-12Z_4f2a9c
- */
-export function generateRunId() {
-  // Create ISO timestamp with colons replaced by dashes for filesystem compatibility
-  const now = new Date();
-  const isoString = now.toISOString();
-  // Format: 2026-01-11T00:59:12.123Z -> 2026-01-11T00-59-12Z
-  const timestamp = isoString.replace(/:/g, '-').replace(/\.\d+Z/, 'Z');
-  
-  // Generate a short hash (6-8 chars)
-  const hash = crypto
-    .randomBytes(4)
-    .toString('hex')
-    .substring(0, 6);
-  
-  return `${timestamp}_${hash}`;
-}
+const ZERO_BUDGET = Object.freeze({
+  maxScanDurationMs: 0,
+  maxInteractionsPerPage: 0,
+  maxUniqueUrls: 0,
+  interactionTimeoutMs: 0,
+  navigationTimeoutMs: 0,
+});
 
-/**
- * Validate a run ID format
- */
-export function isValidRunId(runId) {
-  // Pattern: YYYY-MM-DDTHH-MM-SSZ_hexchars
-  const pattern = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z_[a-f0-9]{6,8}$/;
-  return pattern.test(runId);
+// Deterministic run ID wrapper to align CLI with core generator (no time/randomness)
+export function generateRunId(url = 'about:blank') {
+  let baseOrigin = 'about:blank';
+  try {
+    baseOrigin = new URL(url).origin;
+  } catch {
+    baseOrigin = url;
+  }
+  return generateDeterministicRunId({
+    url,
+    safetyFlags: {},
+    baseOrigin,
+    scanBudget: ZERO_BUDGET,
+    manifestPath: null,
+  });
 }

package/src/cli/util/run-resolver.js

@@ -0,0 +1,64 @@
+/**
+ * PHASE 21.6.1 — Run Resolver
+ * 
+ * Pure filesystem logic to resolve run IDs.
+ * No side effects, no execution dependencies.
+ */
+
+import { readdirSync, statSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Find the latest run ID from .verax/runs/
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {string|null} Latest run ID or null if no runs found
+ */
+export function findLatestRunId(projectDir) {
+  const runsDir = resolve(projectDir, '.verax', 'runs');
+  
+  if (!existsSync(runsDir)) {
+    return null;
+  }
+  
+  try {
+    const runs = readdirSync(runsDir, { withFileTypes: true })
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => {
+        const runPath = resolve(runsDir, dirent.name);
+        try {
+          const stats = statSync(runPath);
+          return {
+            name: dirent.name,
+            mtimeMs: stats.mtimeMs
+          };
+        } catch {
+          return null;
+        }
+      })
+      .filter(run => run !== null);
+    
+    if (runs.length === 0) {
+      return null;
+    }
+    
+    // Sort by modification time (descending) and return latest
+    runs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return runs[0].name;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Validate that a run ID exists
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID to validate
+ * @returns {boolean} Whether run exists
+ */
+export function validateRunId(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  return existsSync(runDir);
+}
+