@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/lib/session-import.cjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+
+/**
+ * Session Import — Import session data from exported files
+ *
+ * Validates session structure and chain integrity
+ * Supports model-specific adapters
+ */
+
+const fs = require('fs');
+const { SessionImportError, SessionNotFoundError } = require('./session-errors.cjs');
+const { defaultLogger: logger } = require('./logger.cjs');
+
+class SessionImport {
+  /**
+   * Create a SessionImport instance
+   * @param {Object} sessionManager - SessionManager instance
+   */
+  constructor(sessionManager) {
+    this.sessionManager = sessionManager;
+  }
+
+  /**
+   * Import a session from file
+   * @param {string} sessionFile - Path to session file
+   * @param {Object} options - Import options
+   * @param {string} [options.sourceModel] - Source model for adapter
+   * @returns {Object} Import result with sessionId and warnings
+   */
+  import(sessionFile, options = {}) {
+    const { sourceModel } = options;
+    const warnings = [];
+
+    // Read and parse file
+    let importedData;
+    try {
+      const content = fs.readFileSync(sessionFile, 'utf-8');
+      importedData = JSON.parse(content);
+    } catch (err) {
+      throw new SessionImportError(`Failed to parse JSON: ${err.message}`, [err.message]);
+    }
+
+    // Handle model-specific format conversion
+    if (sourceModel) {
+      importedData = this.importFromModelSpecificFormat(importedData, sourceModel);
+    }
+
+    // Validate structure
+    const structureValidation = this.validateStructure(importedData);
+    if (!structureValidation.valid) {
+      throw new SessionImportError('Invalid session structure', structureValidation.errors);
+    }
+
+    // Validate session chain
+    const chainValidation = this.validateSessionChain(importedData);
+    if (!chainValidation.valid) {
+      throw new SessionImportError('Invalid session chain', chainValidation.errors);
+    }
+
+    // Validate chain links exist
+    const linksValidation = this.validateChainLinksExist(importedData);
+    if (linksValidation.warnings && linksValidation.warnings.length > 0) {
+      warnings.push(...linksValidation.warnings);
+    }
+
+    // Create new session
+    const newSessionId = this.sessionManager.createSession({
+      model: importedData.metadata?.model,
+      phase: importedData.metadata?.phase,
+      plan: importedData.metadata?.plan
+    });
+
+    // Merge imported context and state
+    const updates = {
+      context: importedData.context || {},
+      state: importedData.state || {}
+    };
+
+    // Add previous session to chain
+    const previousSessionId = importedData.metadata?.session_id;
+    if (previousSessionId) {
+      updates.metadata = {
+        session_chain: [previousSessionId]
+      };
+    }
+
+    this.sessionManager.updateSession(newSessionId, updates);
+
+    logger.info('Session imported', { sessionId: newSessionId, sourceFile: sessionFile });
+
+    return {
+      success: true,
+      sessionId: newSessionId,
+      warnings
+    };
+  }
+
+  /**
+   * Validate session structure
+   * @param {Object} session - Session object
+   * @returns {Object} Validation result
+   */
+  validateStructure(session) {
+    const errors = [];
+
+    // Check for export wrapper or direct session
+    const sessionData = session.session || session;
+
+    if (!sessionData.metadata) {
+      errors.push('Missing metadata section');
+    } else {
+      if (!sessionData.metadata.session_id) {
+        errors.push('Missing metadata.session_id');
+      }
+      if (!sessionData.metadata.started_at) {
+        errors.push('Missing metadata.started_at');
+      }
+      if (!sessionData.metadata.session_version) {
+        errors.push('Missing metadata.session_version');
+      }
+    }
+
+    if (!sessionData.context) {
+      errors.push('Missing context section');
+    } else {
+      if (!Array.isArray(sessionData.context.tasks)) {
+        errors.push('context.tasks must be an array');
+      }
+      if (!Array.isArray(sessionData.context.decisions)) {
+        errors.push('context.decisions must be an array');
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Validate session chain integrity
+   * @param {Object} session - Session object
+   * @returns {Object} Validation result
+   */
+  validateSessionChain(session) {
+    const errors = [];
+    const sessionData = session.session || session;
+
+    if (sessionData.metadata?.session_chain) {
+      const chain = sessionData.metadata.session_chain;
+      const sessionId = sessionData.metadata.session_id;
+
+      if (!Array.isArray(chain)) {
+        errors.push('session_chain must be an array');
+      } else if (chain.includes(sessionId)) {
+        errors.push('Circular reference detected: session_chain includes current session_id');
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Validate chain links exist in session manager
+   * @param {Object} session - Session object
+   * @returns {Object} Validation result with warnings
+   */
+  validateChainLinksExist(session) {
+    const warnings = [];
+    const sessionData = session.session || session;
+
+    if (sessionData.metadata?.session_chain) {
+      const chain = sessionData.metadata.session_chain;
+      const missingLinks = [];
+
+      for (const id of chain) {
+        const linkedSession = this.sessionManager.loadSession(id);
+        if (!linkedSession) {
+          missingLinks.push(id);
+        }
+      }
+
+      if (missingLinks.length > 0) {
+        warnings.push(`Missing chain links: ${missingLinks.join(', ')}`);
+      }
+    }
+
+    return {
+      valid: true,
+      warnings
+    };
+  }
+
+  /**
+   * Import from model-specific format
+   * @param {Object} data - Data to convert
+   * @param {string} sourceModel - Source model name
+   * @returns {Object} Converted session object
+   */
+  importFromModelSpecificFormat(data, sourceModel) {
+    // If data has session wrapper, use it
+    if (data.session) {
+      return data.session;
+    }
+
+    // Model-specific adapters (can be extended)
+    switch (sourceModel.toLowerCase()) {
+      case 'claude':
+        return this._adaptClaudeFormat(data);
+      case 'qwen':
+        return this._adaptQwenFormat(data);
+      case 'openai':
+        return this._adaptOpenAIFormat(data);
+      case 'kimi':
+        return this._adaptKimiFormat(data);
+      default:
+        // Assume standard format
+        return data;
+    }
+  }
+
+  /**
+   * Adapt Claude-specific format
+   * @private
+   */
+  _adaptClaudeFormat(data) {
+    // Claude format adapter (placeholder)
+    return data;
+  }
+
+  /**
+   * Adapt Qwen-specific format
+   * @private
+   */
+  _adaptQwenFormat(data) {
+    // Qwen format adapter (placeholder)
+    return data;
+  }
+
+  /**
+   * Adapt OpenAI-specific format
+   * @private
+   */
+  _adaptOpenAIFormat(data) {
+    // OpenAI format adapter (placeholder)
+    return data;
+  }
+
+  /**
+   * Adapt Kimi-specific format
+   * @private
+   */
+  _adaptKimiFormat(data) {
+    // Kimi format adapter (placeholder)
+    return data;
+  }
+}
+
+module.exports = SessionImport;

package/ez-agents/bin/lib/session-manager.cjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * Session Manager — Core session state persistence module
+ *
+ * Manages session lifecycle: create, load, update, end, list
+ * Sessions stored in .planning/sessions/session-{timestamp}.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safePlanningWriteSync } = require('./planning-write.cjs');
+const { defaultLogger: logger } = require('./logger.cjs');
+
+class SessionManager {
+  /**
+   * Create a SessionManager instance
+   * @param {string} sessionsDir - Directory for session files (default: .planning/sessions)
+   */
+  constructor(sessionsDir = '.planning/sessions') {
+    this.sessionsDir = sessionsDir;
+    this._ensureDir();
+  }
+
+  /**
+   * Ensure sessions directory exists
+   * @private
+   */
+  _ensureDir() {
+    if (!fs.existsSync(this.sessionsDir)) {
+      fs.mkdirSync(this.sessionsDir, { recursive: true });
+      logger.info('Sessions directory created', { dir: this.sessionsDir });
+    }
+  }
+
+  /**
+   * Generate session ID from timestamp
+   * Format: session-YYYYMMDD-HHMMSS
+   * @private
+   * @returns {string} Session ID
+   */
+  _generateSessionId() {
+    const now = new Date();
+    const timestamp = now.toISOString()
+      .replace(/[:.]/g, '-')
+      .replace('T', '-')
+      .slice(0, -5); // Remove milliseconds and Z
+    return `session-${timestamp}`;
+  }
+
+  /**
+   * Deep merge source into target
+   * @private
+   * @param {Object} target - Target object
+   * @param {Object} source - Source object
+   * @returns {Object} Merged object
+   */
+  _deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+      if (source.hasOwnProperty(key)) {
+        if (source[key] instanceof Object && key !== null) {
+          result[key] = this._deepMerge(result[key] || {}, source[key]);
+        } else {
+          result[key] = source[key];
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Create a new session
+   * @param {Object} options - Session options
+   * @param {string} [options.model] - Model identifier
+   * @param {number} [options.phase] - Phase number
+   * @param {number} [options.plan] - Plan number
+   * @param {string} [options.objective] - Session objective
+   * @returns {string} Session ID
+   */
+  createSession(options = {}) {
+    const sessionId = this._generateSessionId();
+    const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+
+    const session = {
+      metadata: {
+        session_id: sessionId,
+        session_version: '1.0',
+        started_at: new Date().toISOString(),
+        ended_at: null,
+        model: options.model || null,
+        phase: options.phase || null,
+        plan: options.plan || null,
+        status: 'active',
+        session_chain: [],
+        token_usage: {
+          input: 0,
+          output: 0,
+          total: 0
+        }
+      },
+      context: {
+        transcript: '',
+        tasks: [],
+        decisions: [],
+        file_changes: [],
+        open_questions: [],
+        blockers: []
+      },
+      state: {
+        current_phase: options.phase || null,
+        current_plan: options.plan || null,
+        incomplete_tasks: [],
+        last_action: null,
+        next_recommended_action: options.objective || null
+      }
+    };
+
+    try {
+      safePlanningWriteSync(sessionPath, JSON.stringify(session, null, 2));
+      logger.info('Session created', { sessionId, sessionPath });
+      return sessionId;
+    } catch (err) {
+      logger.error('Failed to create session', { sessionId, error: err.message });
+      throw err;
+    }
+  }
+
+  /**
+   * Load a session by ID
+   * @param {string} sessionId - Session ID
+   * @returns {Object|null} Session object or null if not found
+   */
+  loadSession(sessionId) {
+    const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+
+    if (!fs.existsSync(sessionPath)) {
+      logger.error('Session not found', { sessionId, sessionPath });
+      return null;
+    }
+
+    try {
+      const content = fs.readFileSync(sessionPath, 'utf-8');
+      const session = JSON.parse(content);
+      logger.info('Session loaded', { sessionId });
+      return session;
+    } catch (err) {
+      logger.error('Failed to load session', { sessionId, error: err.message });
+      return null;
+    }
+  }
+
+  /**
+   * Get the most recent session
+   * @returns {Object|null} Last session or null if none exist
+   */
+  getLastSession() {
+    const sessionFiles = this._getSessionFiles();
+
+    if (sessionFiles.length === 0) {
+      logger.info('No sessions found');
+      return null;
+    }
+
+    // Files are sorted, newest first
+    const lastFile = sessionFiles[0];
+    const sessionId = lastFile.replace('.json', '');
+    return this.loadSession(sessionId);
+  }
+
+  /**
+   * Update a session with new data
+   * @param {string} sessionId - Session ID
+   * @param {Object} updates - Updates to merge into session
+   * @returns {boolean} True on success, false if session not found
+   */
+  updateSession(sessionId, updates) {
+    const session = this.loadSession(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const updatedSession = this._deepMerge(session, updates);
+    const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+
+    try {
+      safePlanningWriteSync(sessionPath, JSON.stringify(updatedSession, null, 2));
+      logger.info('Session updated', { sessionId });
+      return true;
+    } catch (err) {
+      logger.error('Failed to update session', { sessionId, error: err.message });
+      return false;
+    }
+  }
+
+  /**
+   * End a session
+   * @param {string} sessionId - Session ID
+   * @param {Object} finalState - Final state information
+   * @param {string} [finalState.status] - Final status (default: 'completed')
+   * @param {Array} [finalState.incomplete_tasks] - Incomplete tasks
+   * @param {string} [finalState.next_recommended_action] - Next recommended action
+   * @returns {boolean} True on success, false if session not found
+   */
+  endSession(sessionId, finalState = {}) {
+    const session = this.loadSession(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const updates = {
+      metadata: {
+        ended_at: new Date().toISOString(),
+        status: finalState.status || 'completed'
+      },
+      state: {}
+    };
+
+    if (finalState.incomplete_tasks) {
+      updates.state.incomplete_tasks = finalState.incomplete_tasks;
+    }
+
+    if (finalState.next_recommended_action) {
+      updates.state.next_recommended_action = finalState.next_recommended_action;
+    }
+
+    return this.updateSession(sessionId, updates);
+  }
+
+  /**
+   * List all sessions
+   * @returns {Array} Array of session metadata sorted by date (newest first)
+   */
+  listSessions() {
+    const sessionFiles = this._getSessionFiles();
+    const sessions = [];
+
+    for (const file of sessionFiles) {
+      const sessionId = file.replace('.json', '');
+      const session = this.loadSession(sessionId);
+      if (session) {
+        sessions.push({
+          session_id: session.metadata.session_id,
+          started_at: session.metadata.started_at,
+          ended_at: session.metadata.ended_at,
+          model: session.metadata.model,
+          phase: session.metadata.phase,
+          plan: session.metadata.plan,
+          status: session.metadata.status
+        });
+      }
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Get session files sorted by name (newest first)
+   * @private
+   * @returns {Array} Array of filenames
+   */
+  _getSessionFiles() {
+    if (!fs.existsSync(this.sessionsDir)) {
+      return [];
+    }
+
+    try {
+      const files = fs.readdirSync(this.sessionsDir)
+        .filter(file => /^session-.*\.json$/.test(file))
+        .sort()
+        .reverse();
+      return files;
+    } catch (err) {
+      logger.error('Failed to read sessions directory', { error: err.message });
+      return [];
+    }
+  }
+}
+
+module.exports = SessionManager;

package/ez-agents/bin/lib/skill-context.cjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Context — Context schema validation for skill matcher
+ *
+ * Validates and normalizes matcher context:
+ * - stack: object with language, framework, version
+ * - scope: enum [new-feature, bugfix, refactor, migration, maintenance]
+ * - projectType: string (optional)
+ * - mode: enum [greenfield, existing, rapid-mvp, scale-up, maintenance]
+ * - constraints: object with deadline, teamSize, compliance, legacySystems
+ * - taskDescription: string (for keyword matching)
+ * - codebaseFiles: array of strings (for file pattern matching)
+ * - executedCommands: array of strings (for command matching)
+ *
+ * Usage:
+ *   const { validateContext, CONTEXT_SCHEMA } = require('./skill-context.cjs');
+ *   const { valid, errors, normalizedContext } = validateContext(context);
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Context schema definition
+ */
+const CONTEXT_SCHEMA = {
+  stack: {
+    type: 'object',
+    optional: true,
+    properties: {
+      language: { type: 'string', optional: false },
+      framework: { type: 'string', optional: true },
+      version: { type: 'string', optional: true }
+    }
+  },
+  scope: {
+    type: 'enum',
+    values: ['new-feature', 'bugfix', 'refactor', 'migration', 'maintenance'],
+    optional: true
+  },
+  projectType: {
+    type: 'string',
+    optional: true
+  },
+  mode: {
+    type: 'enum',
+    values: ['greenfield', 'existing', 'rapid-mvp', 'scale-up', 'maintenance'],
+    optional: true,
+    normalize: (value) => {
+      const mappings = {
+        'mvp': 'rapid-mvp',
+        'green-field': 'greenfield',
+        'brownfield': 'existing',
+        'scale': 'scale-up',
+        'maint': 'maintenance'
+      };
+      return mappings[value] || value;
+    }
+  },
+  constraints: {
+    type: 'object',
+    optional: true,
+    properties: {
+      deadline: { type: 'string', optional: true },
+      teamSize: { type: 'number', optional: true },
+      compliance: { type: 'array', optional: true },
+      legacySystems: { type: 'array', optional: true }
+    }
+  },
+  taskDescription: { type: 'string', optional: true },
+  codebaseFiles: { type: 'array', optional: true },
+  executedCommands: { type: 'array', optional: true }
+};
+
+/**
+ * Validate and normalize context object
+ * @param {Object} context - Context object to validate
+ * @returns {Object} Validation result: { valid, errors, normalizedContext }
+ */
+function validateContext(context) {
+  const errors = [];
+  const normalized = { ...context };
+
+  if (!context || typeof context !== 'object') {
+    return {
+      valid: false,
+      errors: ['Context must be an object'],
+      normalizedContext: null
+    };
+  }
+
+  // Validate and normalize mode
+  if (context.mode) {
+    const modeSchema = CONTEXT_SCHEMA.mode;
+    if (!modeSchema.values.includes(context.mode)) {
+      const normalizedMode = modeSchema.normalize?.(context.mode);
+      if (normalizedMode && modeSchema.values.includes(normalizedMode)) {
+        normalized.mode = normalizedMode;
+      } else {
+        errors.push(`Invalid mode: ${context.mode}. Valid: ${modeSchema.values.join(', ')}`);
+      }
+    }
+  }
+
+  // Validate scope
+  if (context.scope) {
+    const scopeSchema = CONTEXT_SCHEMA.scope;
+    if (!scopeSchema.values.includes(context.scope)) {
+      errors.push(`Invalid scope: ${context.scope}. Valid: ${scopeSchema.values.join(', ')}`);
+    }
+  }
+
+  // Validate stack structure
+  if (context.stack) {
+    if (!context.stack.language && !context.stack.framework) {
+      errors.push('Stack must have at least language or framework');
+    }
+  }
+
+  // Validate constraints structure
+  if (context.constraints) {
+    if (context.constraints.teamSize && typeof context.constraints.teamSize !== 'number') {
+      errors.push('teamSize must be a number');
+    }
+    if (context.constraints.compliance && !Array.isArray(context.constraints.compliance)) {
+      errors.push('compliance must be an array');
+    }
+  }
+
+  if (errors.length > 0) {
+    logger.warn('Context validation failed', {
+      errorCount: errors.length,
+      errors
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    normalizedContext: errors.length === 0 ? normalized : null
+  };
+}
+
+module.exports = {
+  validateContext,
+  CONTEXT_SCHEMA
+};