agileflow 2.91.0 → 2.92.1

package/lib/consent.js

@@ -0,0 +1,232 @@
+/**
+ * consent.js
+ *
+ * GDPR consent handling for AgileFlow (US-0149)
+ *
+ * Manages privacy consent during setup:
+ * - Prompts user to acknowledge privacy policy
+ * - Stores consent timestamp in .agileflow/config/consent.json
+ * - Supports --accept-privacy flag for CI environments
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+/**
+ * Consent configuration
+ */
+const CONSENT_FILE = '.agileflow/config/consent.json';
+const PRIVACY_POLICY_URL =
+  'https://github.com/projectquestorg/AgileFlow/blob/main/packages/cli/PRIVACY.md';
+
+/**
+ * Consent status types
+ */
+const ConsentStatus = {
+  ACCEPTED: 'accepted',
+  DECLINED: 'declined',
+  PENDING: 'pending',
+};
+
+/**
+ * Check if consent has been given
+ * @returns {{ hasConsent: boolean, consent: Object | null }}
+ */
+function checkConsent() {
+  const consentPath = path.resolve(process.cwd(), CONSENT_FILE);
+
+  try {
+    if (fs.existsSync(consentPath)) {
+      const consent = JSON.parse(fs.readFileSync(consentPath, 'utf8'));
+      return {
+        hasConsent: consent.status === ConsentStatus.ACCEPTED,
+        consent,
+      };
+    }
+  } catch {
+    // Ignore errors, treat as no consent
+  }
+
+  return { hasConsent: false, consent: null };
+}
+
+/**
+ * Record consent
+ * @param {string} status - 'accepted' or 'declined'
+ * @param {Object} options - Additional options
+ * @param {string} options.method - How consent was given ('interactive', 'flag', 'api')
+ * @param {string} options.version - Privacy policy version
+ * @returns {{ ok: boolean, path: string }}
+ */
+function recordConsent(status, options = {}) {
+  const { method = 'interactive', version = '1.0.0' } = options;
+
+  const consentPath = path.resolve(process.cwd(), CONSENT_FILE);
+  const consentDir = path.dirname(consentPath);
+
+  // Ensure directory exists
+  if (!fs.existsSync(consentDir)) {
+    fs.mkdirSync(consentDir, { recursive: true });
+  }
+
+  const consent = {
+    status,
+    timestamp: new Date().toISOString(),
+    method,
+    policy_version: version,
+    policy_url: PRIVACY_POLICY_URL,
+  };
+
+  try {
+    fs.writeFileSync(consentPath, JSON.stringify(consent, null, 2));
+    return { ok: true, path: consentPath };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Prompt user for consent interactively
+ * @param {Object} options - Prompt options
+ * @param {WritableStream} options.output - Output stream (default: process.stdout)
+ * @param {ReadableStream} options.input - Input stream (default: process.stdin)
+ * @returns {Promise<{ accepted: boolean }>}
+ */
+async function promptConsent(options = {}) {
+  const { output = process.stdout, input = process.stdin } = options;
+
+  const rl = readline.createInterface({
+    input,
+    output,
+    terminal: false,
+  });
+
+  // Display privacy notice
+  const notice = `
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                    Privacy Notice                             ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+AgileFlow respects your privacy:
+
+• All data is stored locally on your machine
+• No telemetry, analytics, or tracking
+• No data is transmitted to external servers
+• You can delete all data at any time
+
+For details, see: ${PRIVACY_POLICY_URL}
+
+`;
+
+  output.write(notice);
+
+  return new Promise(resolve => {
+    const question = 'Do you accept the privacy policy? (yes/no): ';
+    output.write(question);
+
+    rl.once('line', answer => {
+      rl.close();
+      const normalized = answer.toLowerCase().trim();
+      const accepted = normalized === 'yes' || normalized === 'y';
+      resolve({ accepted });
+    });
+  });
+}
+
+/**
+ * Handle consent during setup
+ * @param {Object} options - Setup options
+ * @param {boolean} options.acceptPrivacy - --accept-privacy flag was passed
+ * @param {boolean} options.silent - Silent mode (no prompts)
+ * @param {WritableStream} options.output - Output stream
+ * @param {ReadableStream} options.input - Input stream
+ * @returns {Promise<{ ok: boolean, status: string, skipped: boolean }>}
+ */
+async function handleSetupConsent(options = {}) {
+  const {
+    acceptPrivacy = false,
+    silent = false,
+    output = process.stdout,
+    input = process.stdin,
+  } = options;
+
+  // Check if consent already given
+  const { hasConsent, consent } = checkConsent();
+  if (hasConsent) {
+    return { ok: true, status: 'already_consented', skipped: false, consent };
+  }
+
+  // If --accept-privacy flag provided
+  if (acceptPrivacy) {
+    const result = recordConsent(ConsentStatus.ACCEPTED, { method: 'flag' });
+    return { ok: result.ok, status: 'accepted_via_flag', skipped: false };
+  }
+
+  // If silent mode (CI without flag)
+  if (silent) {
+    return { ok: false, status: 'consent_required', skipped: true };
+  }
+
+  // Interactive prompt
+  const { accepted } = await promptConsent({ output, input });
+
+  if (accepted) {
+    const result = recordConsent(ConsentStatus.ACCEPTED, { method: 'interactive' });
+    return { ok: result.ok, status: 'accepted_interactive', skipped: false };
+  } else {
+    const result = recordConsent(ConsentStatus.DECLINED, { method: 'interactive' });
+    return { ok: false, status: 'declined', skipped: false };
+  }
+}
+
+/**
+ * Get consent status for display
+ * @returns {{ status: string, timestamp: string | null, method: string | null }}
+ */
+function getConsentStatus() {
+  const { hasConsent, consent } = checkConsent();
+
+  if (!consent) {
+    return { status: ConsentStatus.PENDING, timestamp: null, method: null };
+  }
+
+  return {
+    status: consent.status,
+    timestamp: consent.timestamp,
+    method: consent.method,
+    policyVersion: consent.policy_version,
+  };
+}
+
+/**
+ * Revoke consent (delete consent file)
+ * @returns {{ ok: boolean }}
+ */
+function revokeConsent() {
+  const consentPath = path.resolve(process.cwd(), CONSENT_FILE);
+
+  try {
+    if (fs.existsSync(consentPath)) {
+      fs.unlinkSync(consentPath);
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+module.exports = {
+  // Constants
+  CONSENT_FILE,
+  PRIVACY_POLICY_URL,
+  ConsentStatus,
+
+  // Functions
+  checkConsent,
+  recordConsent,
+  promptConsent,
+  handleSetupConsent,
+  getConsentStatus,
+  revokeConsent,
+};

package/lib/correlation.js

@@ -0,0 +1,277 @@
+/**
+ * AgileFlow CLI - Correlation ID Management
+ *
+ * Generates and propagates trace IDs and session IDs for event correlation.
+ * Enables filtering and tracing events across complex workflows.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// Global context for correlation IDs
+let currentContext = {
+  traceId: null,
+  sessionId: null,
+  spanId: null,
+  parentSpanId: null,
+};
+
+/**
+ * Generate a unique trace ID (16 hex chars, like OpenTelemetry standard)
+ * @returns {string} Unique trace ID
+ */
+function generateTraceId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * Generate a span ID (8 hex chars)
+ * @returns {string} Unique span ID
+ */
+function generateSpanId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+/**
+ * Generate a session ID based on timestamp and random component
+ * Format: session_YYYYMMDD_HHMMSS_XXXX
+ * @returns {string} Session ID
+ */
+function generateSessionId() {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
+  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
+  const random = crypto.randomBytes(2).toString('hex');
+  return `session_${date}_${time}_${random}`;
+}
+
+/**
+ * Get current correlation context
+ * @returns {{ traceId: string | null, sessionId: string | null, spanId: string | null }}
+ */
+function getContext() {
+  return { ...currentContext };
+}
+
+/**
+ * Set correlation context
+ * @param {Object} context
+ * @param {string} [context.traceId] - Trace ID
+ * @param {string} [context.sessionId] - Session ID
+ * @param {string} [context.spanId] - Span ID
+ * @param {string} [context.parentSpanId] - Parent span ID
+ */
+function setContext(context) {
+  if (context.traceId !== undefined) currentContext.traceId = context.traceId;
+  if (context.sessionId !== undefined) currentContext.sessionId = context.sessionId;
+  if (context.spanId !== undefined) currentContext.spanId = context.spanId;
+  if (context.parentSpanId !== undefined) currentContext.parentSpanId = context.parentSpanId;
+}
+
+/**
+ * Start a new trace (generates new trace_id)
+ * @param {Object} [options]
+ * @param {string} [options.sessionId] - Existing session ID to use
+ * @returns {{ traceId: string, sessionId: string, spanId: string }}
+ */
+function startTrace(options = {}) {
+  const traceId = generateTraceId();
+  const sessionId = options.sessionId || currentContext.sessionId || generateSessionId();
+  const spanId = generateSpanId();
+
+  setContext({
+    traceId,
+    sessionId,
+    spanId,
+    parentSpanId: null,
+  });
+
+  return { traceId, sessionId, spanId };
+}
+
+/**
+ * Start a new span within current trace
+ * @returns {{ traceId: string, sessionId: string, spanId: string, parentSpanId: string | null }}
+ */
+function startSpan() {
+  const parentSpanId = currentContext.spanId;
+  const spanId = generateSpanId();
+
+  setContext({
+    spanId,
+    parentSpanId,
+  });
+
+  return {
+    traceId: currentContext.traceId,
+    sessionId: currentContext.sessionId,
+    spanId,
+    parentSpanId,
+  };
+}
+
+/**
+ * Inject correlation IDs into an event object
+ * @param {Object} event - Event to inject into
+ * @returns {Object} Event with correlation IDs
+ */
+function injectCorrelation(event) {
+  const ctx = getContext();
+  return {
+    ...event,
+    ...(ctx.traceId && { trace_id: ctx.traceId }),
+    ...(ctx.sessionId && { session_id: ctx.sessionId }),
+    ...(ctx.spanId && { span_id: ctx.spanId }),
+    ...(ctx.parentSpanId && { parent_span_id: ctx.parentSpanId }),
+  };
+}
+
+/**
+ * Clear correlation context (for testing or new sessions)
+ */
+function clearContext() {
+  currentContext = {
+    traceId: null,
+    sessionId: null,
+    spanId: null,
+    parentSpanId: null,
+  };
+}
+
+/**
+ * Load session ID from session-state.json if available
+ * @param {string} projectDir - Project directory
+ * @returns {string | null} Session ID or null
+ */
+function loadSessionId(projectDir) {
+  try {
+    const sessionStatePath = path.join(projectDir, 'docs', '09-agents', 'session-state.json');
+    if (fs.existsSync(sessionStatePath)) {
+      const data = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+      return data.session_id || null;
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}
+
+/**
+ * Save session ID to session-state.json
+ * @param {string} projectDir - Project directory
+ * @param {string} sessionId - Session ID to save
+ */
+function saveSessionId(projectDir, sessionId) {
+  try {
+    const sessionStatePath = path.join(projectDir, 'docs', '09-agents', 'session-state.json');
+    let data = {};
+
+    if (fs.existsSync(sessionStatePath)) {
+      data = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+    }
+
+    data.session_id = sessionId;
+    data.updated_at = new Date().toISOString();
+
+    const dir = path.dirname(sessionStatePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(sessionStatePath, JSON.stringify(data, null, 2) + '\n');
+  } catch {
+    // Ignore errors - session ID is not critical
+  }
+}
+
+/**
+ * Initialize correlation context for a project
+ * Loads existing session ID or creates new one
+ * @param {string} projectDir - Project directory
+ * @param {Object} [options]
+ * @param {boolean} [options.newTrace=true] - Start new trace
+ * @returns {{ traceId: string, sessionId: string }}
+ */
+function initializeForProject(projectDir, options = {}) {
+  const { newTrace = true } = options;
+
+  // Load or create session ID
+  let sessionId = loadSessionId(projectDir);
+  if (!sessionId) {
+    sessionId = generateSessionId();
+    saveSessionId(projectDir, sessionId);
+  }
+
+  setContext({ sessionId });
+
+  if (newTrace) {
+    const trace = startTrace({ sessionId });
+    return { traceId: trace.traceId, sessionId };
+  }
+
+  return {
+    traceId: currentContext.traceId || generateTraceId(),
+    sessionId,
+  };
+}
+
+/**
+ * Extract correlation IDs from an event
+ * @param {Object} event - Event object
+ * @returns {{ traceId: string | null, sessionId: string | null, spanId: string | null }}
+ */
+function extractCorrelation(event) {
+  return {
+    traceId: event.trace_id || null,
+    sessionId: event.session_id || null,
+    spanId: event.span_id || null,
+  };
+}
+
+/**
+ * Filter events by trace ID
+ * @param {Array} events - Array of events
+ * @param {string} traceId - Trace ID to filter by
+ * @returns {Array} Filtered events
+ */
+function filterByTraceId(events, traceId) {
+  return events.filter(e => e.trace_id === traceId);
+}
+
+/**
+ * Filter events by session ID
+ * @param {Array} events - Array of events
+ * @param {string} sessionId - Session ID to filter by
+ * @returns {Array} Filtered events
+ */
+function filterBySessionId(events, sessionId) {
+  return events.filter(e => e.session_id === sessionId);
+}
+
+module.exports = {
+  // ID generation
+  generateTraceId,
+  generateSpanId,
+  generateSessionId,
+
+  // Context management
+  getContext,
+  setContext,
+  clearContext,
+  startTrace,
+  startSpan,
+
+  // Event injection/extraction
+  injectCorrelation,
+  extractCorrelation,
+
+  // Project integration
+  initializeForProject,
+  loadSessionId,
+  saveSessionId,
+
+  // Filtering
+  filterByTraceId,
+  filterBySessionId,
+};

package/lib/error-codes.js

@@ -524,6 +524,48 @@ function formatError(error, options = {}) {
   return lines.join('\n');
 }
 
+/**
+ * Create an error result with standardized metadata
+ * This factory produces Result objects compatible with result-schema.js
+ * @param {string} errorCode - Error code (e.g., 'ENOENT', 'ECONFIG')
+ * @param {string} [message] - Optional custom error message
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.context] - Additional context about the error
+ * @param {Error} [options.cause] - Original error that caused this failure
+ * @returns {{ ok: false, error: string, errorCode: string, severity: string, category: string, recoverable: boolean, suggestedFix: string, autoFix: string|null, context?: Object, cause?: Error }}
+ */
+function createErrorResult(errorCode, message, options = {}) {
+  const codeData = ErrorCodes[errorCode] || ErrorCodes.EUNKNOWN;
+
+  return {
+    ok: false,
+    error: message || codeData.message,
+    errorCode: codeData.code,
+    severity: codeData.severity,
+    category: codeData.category,
+    recoverable: codeData.recoverable,
+    suggestedFix: codeData.suggestedFix,
+    autoFix: codeData.autoFix || null,
+    context: options.context,
+    cause: options.cause,
+  };
+}
+
+/**
+ * Create a success result
+ * @template T
+ * @param {T} data - The success data
+ * @param {Object} [meta] - Optional metadata
+ * @returns {{ ok: true, data: T }}
+ */
+function createSuccessResult(data, meta = {}) {
+  return {
+    ok: true,
+    data,
+    ...meta,
+  };
+}
+
 module.exports = {
   // Enums
   Severity,
@@ -541,4 +583,8 @@ module.exports = {
   getSuggestedFix,
   getAutoFix,
   formatError,
+
+  // Result factories (for result-schema.js compatibility)
+  createErrorResult,
+  createSuccessResult,
 };

package/lib/errors.js

@@ -236,10 +236,13 @@ function getCharName(char) {
  * @param {string} filePath - Absolute path to JSON file
  * @param {object} options - Optional settings
  * @param {*} options.defaultValue - Value to return if file doesn't exist (makes missing file not an error)
- * @returns {{ ok: boolean, data?: any, error?: string }}
+ * @param {boolean} options.hidePathInError - Hide file path in error messages (security: default false)
+ * @param {string} options.context - Context for error messages (alternative to exposing path)
+ * @returns {{ ok: boolean, data?: any, error?: string, errorCode?: string }}
  */
 function safeReadJSON(filePath, options = {}) {
-  const { defaultValue } = options;
+  const { defaultValue, hidePathInError = false, context } = options;
+  const pathDisplay = hidePathInError ? context || 'configuration file' : filePath;
 
   try {
     if (!fs.existsSync(filePath)) {
@@ -247,19 +250,58 @@ function safeReadJSON(filePath, options = {}) {
         debugLog('safeReadJSON', { filePath, status: 'missing, using default' });
         return { ok: true, data: defaultValue };
       }
-      const error = `File not found: ${filePath}`;
+      const error = `File not found: ${pathDisplay}`;
       debugLog('safeReadJSON', { filePath, error });
-      return { ok: false, error };
+      return { ok: false, error, errorCode: 'ENOENT' };
     }
 
     const content = fs.readFileSync(filePath, 'utf8');
+
+    // Handle empty files gracefully
+    if (!content.trim()) {
+      if (defaultValue !== undefined) {
+        debugLog('safeReadJSON', { filePath, status: 'empty, using default' });
+        return { ok: true, data: defaultValue };
+      }
+      const error = `File is empty: ${pathDisplay}`;
+      debugLog('safeReadJSON', { filePath, error: 'empty file' });
+      return { ok: false, error, errorCode: 'EPARSE' };
+    }
+
     const data = JSON.parse(content);
     debugLog('safeReadJSON', { filePath, status: 'success' });
     return { ok: true, data };
   } catch (err) {
-    const error = `Failed to read JSON from ${filePath}: ${err.message}`;
+    // Detect specific JSON parse errors
+    let errorCode = 'EPARSE';
+    let errorMessage = `Failed to parse JSON`;
+
+    if (err.code === 'EACCES' || err.code === 'EPERM') {
+      errorCode = 'EACCES';
+      errorMessage = `Permission denied reading file`;
+    } else if (err.message && err.message.includes('Unexpected')) {
+      // JSON syntax error - don't expose full content
+      errorMessage = `Invalid JSON syntax`;
+      if (err.message.includes('position')) {
+        // Extract position info but not content
+        const posMatch = err.message.match(/position (\d+)/);
+        if (posMatch) {
+          errorMessage = `Invalid JSON syntax near position ${posMatch[1]}`;
+        }
+      }
+    } else if (err.message && err.message.includes('token')) {
+      errorMessage = `Invalid JSON: unexpected token`;
+    }
+
+    // Add context if not hiding path
+    if (!hidePathInError) {
+      errorMessage = `${errorMessage} in ${pathDisplay}`;
+    } else if (context) {
+      errorMessage = `${errorMessage} in ${context}`;
+    }
+
     debugLog('safeReadJSON', { filePath, error: err.message });
-    return { ok: false, error };
+    return { ok: false, error: errorMessage, errorCode };
   }
 }