kodelyth-ecc 1.2.0

package/scripts/lib/inspection.js

@@ -0,0 +1,212 @@
+'use strict';
+
+const DEFAULT_FAILURE_THRESHOLD = 3;
+const DEFAULT_WINDOW_SIZE = 50;
+
+const FAILURE_OUTCOMES = new Set(['failure', 'failed', 'error']);
+
+/**
+ * Normalize a failure reason string for grouping.
+ * Strips timestamps, UUIDs, file paths, and numeric suffixes.
+ */
+function normalizeFailureReason(reason) {
+  if (!reason || typeof reason !== 'string') {
+    return 'unknown';
+  }
+
+  return reason
+    .trim()
+    .toLowerCase()
+    // Strip ISO timestamps (note: already lowercased, so t/z not T/Z)
+    .replace(/\d{4}-\d{2}-\d{2}[t ]\d{2}:\d{2}:\d{2}[.\dz]*/g, '<timestamp>')
+    // Strip UUIDs (already lowercased)
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '<uuid>')
+    // Strip file paths
+    .replace(/\/[\w./-]+/g, '<path>')
+    // Collapse whitespace
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Group skill runs by skill ID and normalized failure reason.
+ *
+ * @param {Array} skillRuns - Array of skill run objects
+ * @returns {Map<string, { skillId: string, normalizedReason: string, runs: Array }>}
+ */
+function groupFailures(skillRuns) {
+  const groups = new Map();
+
+  for (const run of skillRuns) {
+    const outcome = String(run.outcome || '').toLowerCase();
+    if (!FAILURE_OUTCOMES.has(outcome)) {
+      continue;
+    }
+
+    const normalizedReason = normalizeFailureReason(run.failureReason);
+    const key = `${run.skillId}::${normalizedReason}`;
+
+    if (!groups.has(key)) {
+      groups.set(key, {
+        skillId: run.skillId,
+        normalizedReason,
+        runs: [],
+      });
+    }
+
+    groups.get(key).runs.push(run);
+  }
+
+  return groups;
+}
+
+/**
+ * Detect recurring failure patterns from skill runs.
+ *
+ * @param {Array} skillRuns - Array of skill run objects (newest first)
+ * @param {Object} [options]
+ * @param {number} [options.threshold=3] - Minimum failure count to trigger pattern detection
+ * @returns {Array<Object>} Array of detected patterns sorted by count descending
+ */
+function detectPatterns(skillRuns, options = {}) {
+  const threshold = options.threshold ?? DEFAULT_FAILURE_THRESHOLD;
+  const groups = groupFailures(skillRuns);
+  const patterns = [];
+
+  for (const [, group] of groups) {
+    if (group.runs.length < threshold) {
+      continue;
+    }
+
+    const sortedRuns = [...group.runs].sort(
+      (a, b) => (b.createdAt || '').localeCompare(a.createdAt || '')
+    );
+
+    const firstSeen = sortedRuns[sortedRuns.length - 1].createdAt || null;
+    const lastSeen = sortedRuns[0].createdAt || null;
+    const sessionIds = [...new Set(sortedRuns.map(r => r.sessionId).filter(Boolean))];
+    const versions = [...new Set(sortedRuns.map(r => r.skillVersion).filter(Boolean))];
+
+    // Collect unique raw failure reasons for this normalized group
+    const rawReasons = [...new Set(sortedRuns.map(r => r.failureReason).filter(Boolean))];
+
+    patterns.push({
+      skillId: group.skillId,
+      normalizedReason: group.normalizedReason,
+      count: group.runs.length,
+      firstSeen,
+      lastSeen,
+      sessionIds,
+      versions,
+      rawReasons,
+      runIds: sortedRuns.map(r => r.id),
+    });
+  }
+
+  // Sort by count descending, then by lastSeen descending
+  return patterns.sort((a, b) => {
+    if (b.count !== a.count) return b.count - a.count;
+    return (b.lastSeen || '').localeCompare(a.lastSeen || '');
+  });
+}
+
+/**
+ * Generate an inspection report from detected patterns.
+ *
+ * @param {Array} patterns - Output from detectPatterns()
+ * @param {Object} [options]
+ * @param {string} [options.generatedAt] - ISO timestamp for the report
+ * @returns {Object} Inspection report
+ */
+function generateReport(patterns, options = {}) {
+  const generatedAt = options.generatedAt || new Date().toISOString();
+
+  if (patterns.length === 0) {
+    return {
+      generatedAt,
+      status: 'clean',
+      patternCount: 0,
+      patterns: [],
+      summary: 'No recurring failure patterns detected.',
+    };
+  }
+
+  const totalFailures = patterns.reduce((sum, p) => sum + p.count, 0);
+  const affectedSkills = [...new Set(patterns.map(p => p.skillId))];
+
+  return {
+    generatedAt,
+    status: 'attention_needed',
+    patternCount: patterns.length,
+    totalFailures,
+    affectedSkills,
+    patterns: patterns.map(p => ({
+      skillId: p.skillId,
+      normalizedReason: p.normalizedReason,
+      count: p.count,
+      firstSeen: p.firstSeen,
+      lastSeen: p.lastSeen,
+      sessionIds: p.sessionIds,
+      versions: p.versions,
+      rawReasons: p.rawReasons.slice(0, 5),
+      suggestedAction: suggestAction(p),
+    })),
+    summary: `Found ${patterns.length} recurring failure pattern(s) across ${affectedSkills.length} skill(s) (${totalFailures} total failures).`,
+  };
+}
+
+/**
+ * Suggest a remediation action based on pattern characteristics.
+ */
+function suggestAction(pattern) {
+  const reason = pattern.normalizedReason;
+
+  if (reason.includes('timeout')) {
+    return 'Increase timeout or optimize skill execution time.';
+  }
+  if (reason.includes('permission') || reason.includes('denied') || reason.includes('auth')) {
+    return 'Check tool permissions and authentication configuration.';
+  }
+  if (reason.includes('not found') || reason.includes('missing')) {
+    return 'Verify required files/dependencies exist before skill execution.';
+  }
+  if (reason.includes('parse') || reason.includes('syntax') || reason.includes('json')) {
+    return 'Review input/output format expectations and add validation.';
+  }
+  if (pattern.versions.length > 1) {
+    return 'Failure spans multiple versions. Consider rollback to last stable version.';
+  }
+
+  return 'Investigate root cause and consider adding error handling.';
+}
+
+/**
+ * Run full inspection pipeline: query skill runs, detect patterns, generate report.
+ *
+ * @param {Object} store - State store instance with listRecentSessions, getSessionDetail
+ * @param {Object} [options]
+ * @param {number} [options.threshold] - Minimum failure count
+ * @param {number} [options.windowSize] - Number of recent skill runs to analyze
+ * @returns {Object} Inspection report
+ */
+function inspect(store, options = {}) {
+  const windowSize = options.windowSize ?? DEFAULT_WINDOW_SIZE;
+  const threshold = options.threshold ?? DEFAULT_FAILURE_THRESHOLD;
+
+  const status = store.getStatus({ recentSkillRunLimit: windowSize });
+  const skillRuns = status.skillRuns.recent || [];
+
+  const patterns = detectPatterns(skillRuns, { threshold });
+  return generateReport(patterns, { generatedAt: status.generatedAt });
+}
+
+module.exports = {
+  DEFAULT_FAILURE_THRESHOLD,
+  DEFAULT_WINDOW_SIZE,
+  detectPatterns,
+  generateReport,
+  groupFailures,
+  inspect,
+  normalizeFailureReason,
+  suggestAction,
+};

package/scripts/lib/install/apply.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { writeInstallState } = require('../install-state');
+const { filterMcpConfig, parseDisabledMcpServers } = require('../mcp-config');
+
+function readJsonObject(filePath, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to parse ${label} at ${filePath}: ${error.message}`);
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Invalid ${label} at ${filePath}: expected a JSON object`);
+  }
+
+  return parsed;
+}
+
+function replacePluginRootPlaceholders(value, pluginRoot) {
+  if (!pluginRoot) {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    return value.split('${CLAUDE_PLUGIN_ROOT}').join(pluginRoot);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => replacePluginRootPlaceholders(item, pluginRoot));
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        replacePluginRootPlaceholders(nestedValue, pluginRoot),
+      ])
+    );
+  }
+
+  return value;
+}
+
+function buildLegacyHookSignature(entry, pluginRoot) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return null;
+  }
+
+  const normalizedEntry = replacePluginRootPlaceholders(entry, pluginRoot);
+
+  if (typeof normalizedEntry.matcher !== 'string' || !Array.isArray(normalizedEntry.hooks)) {
+    return null;
+  }
+
+  const hookSignature = normalizedEntry.hooks.map(hook => JSON.stringify({
+    type: hook && typeof hook === 'object' ? hook.type : undefined,
+    command: hook && typeof hook === 'object' ? hook.command : undefined,
+    timeout: hook && typeof hook === 'object' ? hook.timeout : undefined,
+    async: hook && typeof hook === 'object' ? hook.async : undefined,
+  }));
+
+  return JSON.stringify({
+    matcher: normalizedEntry.matcher,
+    hooks: hookSignature,
+  });
+}
+
+function getHookEntryAliases(entry, pluginRoot) {
+  const aliases = [];
+
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return aliases;
+  }
+
+  const normalizedEntry = replacePluginRootPlaceholders(entry, pluginRoot);
+
+  if (typeof normalizedEntry.id === 'string' && normalizedEntry.id.trim().length > 0) {
+    aliases.push(`id:${normalizedEntry.id.trim()}`);
+  }
+
+  const legacySignature = buildLegacyHookSignature(normalizedEntry, pluginRoot);
+  if (legacySignature) {
+    aliases.push(`legacy:${legacySignature}`);
+  }
+
+  aliases.push(`json:${JSON.stringify(normalizedEntry)}`);
+
+  return aliases;
+}
+
+function mergeHookEntries(existingEntries, incomingEntries, pluginRoot) {
+  const mergedEntries = [];
+  const seenEntries = new Set();
+
+  for (const entry of [...existingEntries, ...incomingEntries]) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      continue;
+    }
+
+    if ('id' in entry && typeof entry.id !== 'string') {
+      continue;
+    }
+
+    const aliases = getHookEntryAliases(entry, pluginRoot);
+    if (aliases.some(alias => seenEntries.has(alias))) {
+      continue;
+    }
+
+    for (const alias of aliases) {
+      seenEntries.add(alias);
+    }
+    mergedEntries.push(replacePluginRootPlaceholders(entry, pluginRoot));
+  }
+
+  return mergedEntries;
+}
+
+function findHooksSourcePath(plan, hooksDestinationPath) {
+  const operation = plan.operations.find(item => item.destinationPath === hooksDestinationPath);
+  return operation ? operation.sourcePath : null;
+}
+
+function isMcpConfigPath(filePath) {
+  const basename = path.basename(String(filePath || ''));
+  return basename === '.mcp.json' || basename === 'mcp.json';
+}
+
+function buildFilteredMcpWrites(plan) {
+  const disabledServers = parseDisabledMcpServers(process.env.ECC_DISABLED_MCPS);
+  if (disabledServers.length === 0) {
+    return [];
+  }
+
+  const writes = [];
+
+  for (const operation of plan.operations) {
+    if (!isMcpConfigPath(operation.destinationPath) || !operation.sourcePath || !fs.existsSync(operation.sourcePath)) {
+      continue;
+    }
+
+    let sourceConfig;
+    try {
+      sourceConfig = readJsonObject(operation.sourcePath, 'MCP config');
+    } catch {
+      continue;
+    }
+
+    if (!sourceConfig.mcpServers || typeof sourceConfig.mcpServers !== 'object' || Array.isArray(sourceConfig.mcpServers)) {
+      continue;
+    }
+
+    const filtered = filterMcpConfig(sourceConfig, disabledServers);
+    if (filtered.removed.length === 0) {
+      continue;
+    }
+
+    writes.push({
+      destinationPath: operation.destinationPath,
+      filteredConfig: filtered.config,
+    });
+  }
+
+  return writes;
+}
+
+function buildMergedSettings(plan) {
+  if (!plan.adapter || plan.adapter.target !== 'claude') {
+    return null;
+  }
+
+  const pluginRoot = plan.targetRoot;
+  const hooksDestinationPath = path.join(plan.targetRoot, 'hooks', 'hooks.json');
+  const hooksSourcePath = findHooksSourcePath(plan, hooksDestinationPath) || hooksDestinationPath;
+  if (!fs.existsSync(hooksSourcePath)) {
+    return null;
+  }
+
+  const hooksConfig = readJsonObject(hooksSourcePath, 'hooks config');
+  const incomingHooks = replacePluginRootPlaceholders(hooksConfig.hooks, pluginRoot);
+  if (!incomingHooks || typeof incomingHooks !== 'object' || Array.isArray(incomingHooks)) {
+    throw new Error(`Invalid hooks config at ${hooksSourcePath}: expected "hooks" to be a JSON object`);
+  }
+
+  const settingsPath = path.join(plan.targetRoot, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    settings = readJsonObject(settingsPath, 'existing settings');
+  }
+
+  const existingHooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+    ? settings.hooks
+    : {};
+  const mergedHooks = { ...existingHooks };
+
+  for (const [eventName, incomingEntries] of Object.entries(incomingHooks)) {
+    const currentEntries = Array.isArray(existingHooks[eventName]) ? existingHooks[eventName] : [];
+    const nextEntries = Array.isArray(incomingEntries) ? incomingEntries : [];
+    mergedHooks[eventName] = mergeHookEntries(currentEntries, nextEntries, pluginRoot);
+  }
+
+  const mergedSettings = {
+    ...settings,
+    hooks: mergedHooks,
+  };
+
+  return {
+    settingsPath,
+    mergedSettings,
+    hooksDestinationPath,
+    resolvedHooksConfig: {
+      ...hooksConfig,
+      hooks: incomingHooks,
+    },
+  };
+}
+
+function applyInstallPlan(plan) {
+  const mergedSettingsPlan = buildMergedSettings(plan);
+  const filteredMcpWrites = buildFilteredMcpWrites(plan);
+
+  for (const operation of plan.operations) {
+    fs.mkdirSync(path.dirname(operation.destinationPath), { recursive: true });
+    fs.copyFileSync(operation.sourcePath, operation.destinationPath);
+  }
+
+  if (mergedSettingsPlan) {
+    fs.mkdirSync(path.dirname(mergedSettingsPlan.hooksDestinationPath), { recursive: true });
+    fs.writeFileSync(
+      mergedSettingsPlan.hooksDestinationPath,
+      JSON.stringify(mergedSettingsPlan.resolvedHooksConfig, null, 2) + '\n',
+      'utf8'
+    );
+    fs.mkdirSync(path.dirname(mergedSettingsPlan.settingsPath), { recursive: true });
+    fs.writeFileSync(
+      mergedSettingsPlan.settingsPath,
+      JSON.stringify(mergedSettingsPlan.mergedSettings, null, 2) + '\n',
+      'utf8'
+    );
+  }
+
+  for (const writePlan of filteredMcpWrites) {
+    fs.mkdirSync(path.dirname(writePlan.destinationPath), { recursive: true });
+    fs.writeFileSync(
+      writePlan.destinationPath,
+      JSON.stringify(writePlan.filteredConfig, null, 2) + '\n',
+      'utf8'
+    );
+  }
+
+  writeInstallState(plan.installStatePath, plan.statePreview);
+
+  return {
+    ...plan,
+    applied: true,
+  };
+}
+
+module.exports = {
+  applyInstallPlan,
+};

package/scripts/lib/install/config.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+
+const DEFAULT_INSTALL_CONFIG = 'ecc-install.json';
+const CONFIG_SCHEMA_PATH = path.join(__dirname, '..', '..', '..', 'schemas', 'ecc-install-config.schema.json');
+
+let cachedValidator = null;
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${label}: ${error.message}`);
+  }
+}
+
+function getValidator() {
+  if (cachedValidator) {
+    return cachedValidator;
+  }
+
+  const schema = readJson(CONFIG_SCHEMA_PATH, 'ecc-install-config.schema.json');
+  const ajv = new Ajv({ allErrors: true });
+  cachedValidator = ajv.compile(schema);
+  return cachedValidator;
+}
+
+function dedupeStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : []).map(value => String(value).trim()).filter(Boolean))];
+}
+
+function formatValidationErrors(errors = []) {
+  return errors.map(error => `${error.instancePath || '/'} ${error.message}`).join('; ');
+}
+
+function resolveInstallConfigPath(configPath, options = {}) {
+  if (!configPath) {
+    throw new Error('An install config path is required');
+  }
+
+  const cwd = options.cwd || process.cwd();
+  return path.isAbsolute(configPath)
+    ? configPath
+    : path.normalize(path.join(cwd, configPath));
+}
+
+function findDefaultInstallConfigPath(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const candidatePath = path.join(cwd, DEFAULT_INSTALL_CONFIG);
+  return fs.existsSync(candidatePath) ? candidatePath : null;
+}
+
+function loadInstallConfig(configPath, options = {}) {
+  const resolvedPath = resolveInstallConfigPath(configPath, options);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Install config not found: ${resolvedPath}`);
+  }
+
+  const raw = readJson(resolvedPath, path.basename(resolvedPath));
+  const validator = getValidator();
+
+  if (!validator(raw)) {
+    throw new Error(
+      `Invalid install config ${resolvedPath}: ${formatValidationErrors(validator.errors)}`
+    );
+  }
+
+  return {
+    path: resolvedPath,
+    version: raw.version,
+    target: raw.target || null,
+    profileId: raw.profile || null,
+    moduleIds: dedupeStrings(raw.modules),
+    includeComponentIds: dedupeStrings(raw.include),
+    excludeComponentIds: dedupeStrings(raw.exclude),
+    options: raw.options && typeof raw.options === 'object' ? { ...raw.options } : {},
+  };
+}
+
+module.exports = {
+  DEFAULT_INSTALL_CONFIG,
+  findDefaultInstallConfigPath,
+  loadInstallConfig,
+  resolveInstallConfigPath,
+};

package/scripts/lib/install/request.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const { validateInstallModuleIds } = require('../install-manifests');
+
+const LEGACY_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity'];
+
+function dedupeStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : []).map(value => String(value).trim()).filter(Boolean))];
+}
+
+function parseInstallArgs(argv) {
+  const args = argv.slice(2);
+  const parsed = {
+    target: null,
+    dryRun: false,
+    json: false,
+    help: false,
+    configPath: null,
+    profileId: null,
+    moduleIds: [],
+    includeComponentIds: [],
+    excludeComponentIds: [],
+    languages: [],
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--target') {
+      parsed.target = args[index + 1] || null;
+      index += 1;
+    } else if (arg === '--config') {
+      parsed.configPath = args[index + 1] || null;
+      index += 1;
+    } else if (arg === '--profile') {
+      parsed.profileId = args[index + 1] || null;
+      index += 1;
+    } else if (arg === '--modules') {
+      const raw = args[index + 1] || '';
+      parsed.moduleIds = dedupeStrings(raw.split(','));
+      index += 1;
+    } else if (arg === '--with') {
+      const componentId = args[index + 1] || '';
+      if (componentId.trim()) {
+        parsed.includeComponentIds.push(componentId.trim());
+      }
+      index += 1;
+    } else if (arg === '--without') {
+      const componentId = args[index + 1] || '';
+      if (componentId.trim()) {
+        parsed.excludeComponentIds.push(componentId.trim());
+      }
+      index += 1;
+    } else if (arg === '--dry-run') {
+      parsed.dryRun = true;
+    } else if (arg === '--json') {
+      parsed.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown argument: ${arg}`);
+    } else {
+      parsed.languages.push(arg);
+    }
+  }
+
+  return parsed;
+}
+
+function normalizeInstallRequest(options = {}) {
+  const config = options.config && typeof options.config === 'object'
+    ? options.config
+    : null;
+  const profileId = options.profileId || config?.profileId || null;
+  const moduleIds = validateInstallModuleIds(
+    dedupeStrings([...(config?.moduleIds || []), ...(options.moduleIds || [])])
+  );
+  const includeComponentIds = dedupeStrings([
+    ...(config?.includeComponentIds || []),
+    ...(options.includeComponentIds || []),
+  ]);
+  const excludeComponentIds = dedupeStrings([
+    ...(config?.excludeComponentIds || []),
+    ...(options.excludeComponentIds || []),
+  ]);
+  const legacyLanguages = dedupeStrings(dedupeStrings([
+    ...(Array.isArray(options.legacyLanguages) ? options.legacyLanguages : []),
+    ...(Array.isArray(options.languages) ? options.languages : []),
+  ]).map(language => language.toLowerCase()));
+  const target = options.target || config?.target || 'claude';
+  const hasManifestBaseSelection = Boolean(profileId) || moduleIds.length > 0 || includeComponentIds.length > 0;
+  const usingManifestMode = hasManifestBaseSelection || excludeComponentIds.length > 0;
+
+  if (usingManifestMode && legacyLanguages.length > 0) {
+    throw new Error(
+      'Legacy language arguments cannot be combined with --profile, --modules, --with, --without, or manifest config selections'
+    );
+  }
+
+  if (!options.help && !hasManifestBaseSelection && legacyLanguages.length === 0) {
+    throw new Error('No install profile, module IDs, included components, or legacy languages were provided');
+  }
+
+  return {
+    mode: usingManifestMode ? 'manifest' : 'legacy-compat',
+    target,
+    profileId,
+    moduleIds,
+    includeComponentIds,
+    excludeComponentIds,
+    legacyLanguages,
+    configPath: config?.path || options.configPath || null,
+  };
+}
+
+module.exports = {
+  LEGACY_INSTALL_TARGETS,
+  normalizeInstallRequest,
+  parseInstallArgs,
+};