@veraxhq/verax 0.3.0 → 0.4.0

package/src/cli/util/paths.js

@@ -1,6 +1,5 @@
 import { join, isAbsolute } from 'path';
 import { mkdirSync } from 'fs';
-import { buildRunArtifactPaths } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Build run artifact paths
@@ -8,8 +7,18 @@ import { buildRunArtifactPaths } from '../../verax/core/artifacts/registry.js';
 export function getRunPaths(projectRoot, outDir, runId) {
   const outBase = isAbsolute(outDir) ? outDir : join(projectRoot, outDir);
   const baseDir = join(outBase, 'runs', runId);
-
-  return buildRunArtifactPaths(baseDir);
+  
+  return {
+    baseDir,
+    runStatusJson: join(baseDir, 'run.status.json'),
+    runMetaJson: join(baseDir, 'run.meta.json'),
+    summaryJson: join(baseDir, 'summary.json'),
+    findingsJson: join(baseDir, 'findings.json'),
+    tracesJsonl: join(baseDir, 'traces.jsonl'),
+    evidenceDir: join(baseDir, 'evidence'),
+    learnJson: join(baseDir, 'learn.json'),
+    observeJson: join(baseDir, 'observe.json'),
+  };
 }
 
 /**

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

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { resolve, dirname } from 'path';
-import { assertExecutionBootstrapAllowed } from './bootstrap-guard.js';
 
 /**
  * Project Discovery Module
@@ -22,8 +21,6 @@ import { assertExecutionBootstrapAllowed } from './bootstrap-guard.js';
  * @returns {Promise<ProjectProfile>}
  */
 export async function discoverProject(srcPath) {
-  // PHASE 21.6.1: Runtime guard - crash if called during inspection
-  assertExecutionBootstrapAllowed('discoverProject');
   const projectRoot = resolve(srcPath);
   
   // Find the nearest package.json
@@ -36,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;
@@ -67,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
  */
@@ -298,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

@@ -6,10 +6,10 @@ import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
  * Write project profile artifact
  */
 export function writeProjectJson(runPaths, projectProfile) {
-  const projectJsonPath = resolve(runPaths.baseDir, ARTIFACT_REGISTRY.project.filename);
+  const projectJsonPath = resolve(runPaths.baseDir, 'project.json');
   
   const projectJson = {
-    contractVersion: 1,
+    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,
+  });
 }