aw-ecc 1.4.21

package/scripts/lib/hook-flags.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Shared hook enable/disable controls.
+ *
+ * Controls:
+ * - ECC_HOOK_PROFILE=minimal|standard|strict (default: standard)
+ * - ECC_DISABLED_HOOKS=comma,separated,hook,ids
+ */
+
+'use strict';
+
+const VALID_PROFILES = new Set(['minimal', 'standard', 'strict']);
+
+function normalizeId(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function getHookProfile() {
+  const raw = String(process.env.ECC_HOOK_PROFILE || 'standard').trim().toLowerCase();
+  return VALID_PROFILES.has(raw) ? raw : 'standard';
+}
+
+function getDisabledHookIds() {
+  const raw = String(process.env.ECC_DISABLED_HOOKS || '');
+  if (!raw.trim()) return new Set();
+
+  return new Set(
+    raw
+      .split(',')
+      .map(v => normalizeId(v))
+      .filter(Boolean)
+  );
+}
+
+function parseProfiles(rawProfiles, fallback = ['standard', 'strict']) {
+  if (!rawProfiles) return [...fallback];
+
+  if (Array.isArray(rawProfiles)) {
+    const parsed = rawProfiles
+      .map(v => String(v || '').trim().toLowerCase())
+      .filter(v => VALID_PROFILES.has(v));
+    return parsed.length > 0 ? parsed : [...fallback];
+  }
+
+  const parsed = String(rawProfiles)
+    .split(',')
+    .map(v => v.trim().toLowerCase())
+    .filter(v => VALID_PROFILES.has(v));
+
+  return parsed.length > 0 ? parsed : [...fallback];
+}
+
+function isHookEnabled(hookId, options = {}) {
+  const id = normalizeId(hookId);
+  if (!id) return true;
+
+  const disabled = getDisabledHookIds();
+  if (disabled.has(id)) {
+    return false;
+  }
+
+  const profile = getHookProfile();
+  const allowedProfiles = parseProfiles(options.profiles);
+  return allowedProfiles.includes(profile);
+}
+
+module.exports = {
+  VALID_PROFILES,
+  normalizeId,
+  getHookProfile,
+  getDisabledHookIds,
+  parseProfiles,
+  isHookEnabled,
+};

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,23 @@
+'use strict';
+
+const fs = require('fs');
+
+const { writeInstallState } = require('../install-state');
+
+function applyInstallPlan(plan) {
+  for (const operation of plan.operations) {
+    fs.mkdirSync(require('path').dirname(operation.destinationPath), { recursive: true });
+    fs.copyFileSync(operation.sourcePath, operation.destinationPath);
+  }
+
+  writeInstallState(plan.installStatePath, plan.statePreview);
+
+  return {
+    ...plan,
+    applied: true,
+  };
+}
+
+module.exports = {
+  applyInstallPlan,
+};

package/scripts/lib/install/config.js

@@ -0,0 +1,82 @@
+'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 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,
+  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,
+};

package/scripts/lib/install/runtime.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const {
+  createLegacyCompatInstallPlan,
+  createLegacyInstallPlan,
+  createManifestInstallPlan,
+} = require('../install-executor');
+
+function createInstallPlanFromRequest(request, options = {}) {
+  if (!request || typeof request !== 'object') {
+    throw new Error('A normalized install request is required');
+  }
+
+  if (request.mode === 'manifest') {
+    return createManifestInstallPlan({
+      target: request.target,
+      profileId: request.profileId,
+      moduleIds: request.moduleIds,
+      includeComponentIds: request.includeComponentIds,
+      excludeComponentIds: request.excludeComponentIds,
+      projectRoot: options.projectRoot,
+      homeDir: options.homeDir,
+      sourceRoot: options.sourceRoot,
+    });
+  }
+
+  if (request.mode === 'legacy-compat') {
+    return createLegacyCompatInstallPlan({
+      target: request.target,
+      legacyLanguages: request.legacyLanguages,
+      projectRoot: options.projectRoot,
+      homeDir: options.homeDir,
+      claudeRulesDir: options.claudeRulesDir,
+      sourceRoot: options.sourceRoot,
+    });
+  }
+
+  if (request.mode === 'legacy') {
+    return createLegacyInstallPlan({
+      target: request.target,
+      languages: request.languages,
+      projectRoot: options.projectRoot,
+      homeDir: options.homeDir,
+      claudeRulesDir: options.claudeRulesDir,
+      sourceRoot: options.sourceRoot,
+    });
+  }
+
+  throw new Error(`Unsupported install request mode: ${request.mode}`);
+}
+
+module.exports = {
+  createInstallPlanFromRequest,
+};