scc-universal 1.1.0

package/scripts/lib/hook-flags.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Shared hook enable/disable controls.
+ *
+ * Controls:
+ * - SCC_HOOK_PROFILE=minimal|standard|strict (default: standard)
+ * - SCC_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.SCC_HOOK_PROFILE || 'standard').trim().toLowerCase();
+  return VALID_PROFILES.has(raw) ? raw : 'standard';
+}
+
+function getDisabledHookIds() {
+  const raw = String(process.env.SCC_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/install-config.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * install-config.js — Loads and validates SCC install config files.
+ *
+ * Config files (scc-install.json) let teams commit install preferences to their repo.
+ * Read-only — SCC never writes config files. CLI args override config values.
+ *
+ * Validates against schemas/scc-install-config.schema.json via AJV.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { assertAgainstSchema, formatErrors } = require('./schema-validator');
+
+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schemas', 'scc-install-config.schema.json');
+
+/**
+ * Deduplicate an array of strings while preserving order.
+ */
+function dedupeStrings(arr) {
+  return [...new Set(arr)];
+}
+
+/**
+ * Resolve a config file path. Relative paths resolve against cwd.
+ *
+ * @param {string} configPath - path to config file
+ * @returns {string} resolved absolute path
+ */
+function resolveConfigPath(configPath) {
+  if (!configPath) throw new Error('Config path is required');
+  return path.resolve(configPath);
+}
+
+/**
+ * Load and validate an SCC install config file.
+ *
+ * @param {string} configPath - path to scc-install.json
+ * @returns {Object} normalized config: { path, version, target, profile, modules, include, exclude, options }
+ * @throws {Error} if file not found, invalid JSON, or schema validation fails
+ */
+function loadInstallConfig(configPath) {
+  const resolved = resolveConfigPath(configPath);
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Install config not found: ${resolved}`);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  } catch (err) {
+    throw new Error(`Invalid JSON in config ${resolved}: ${err.message}`, { cause: err });
+  }
+
+  // Validate against schema
+  assertAgainstSchema(SCHEMA_PATH, raw, `install config ${path.basename(resolved)}`);
+
+  // Normalize and deduplicate
+  return {
+    path: resolved,
+    version: raw.version,
+    target: raw.target || null,
+    profile: raw.profile || null,
+    modules: dedupeStrings(raw.modules || []),
+    include: dedupeStrings(raw.include || []),
+    exclude: dedupeStrings(raw.exclude || []),
+    options: raw.options || {},
+  };
+}
+
+module.exports = { loadInstallConfig, resolveConfigPath };

package/scripts/lib/install-executor.js

@@ -0,0 +1,363 @@
+'use strict';
+
+/**
+ * install-executor.js — Executes SCC content installation.
+ *
+ * Handles file copying for different targets:
+ *   - claude   → .claude/ subdirs (agents, skills, commands)
+ *   - cursor   → .cursor/ subdirs (agents, skills)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { copyFile, readJson, fileExists, simpleHash } = require('./utils');
+const { saveState } = require('./state-store');
+const { transformSkillDir } = require('./skill-adapter');
+const { transformAgentFile } = require('./agent-adapter');
+
+const VALID_TARGETS = ['claude', 'cursor'];
+const VALID_PROFILES = ['apex', 'lwc', 'full'];
+
+/**
+ * Resolve target directory mappings.
+ * @param {string} target
+ * @param {string} projectRoot - directory where content is being installed
+ */
+function getTargetDirs(target, projectRoot) {
+  switch (target) {
+    case 'claude':
+      return {
+        agents: path.join(projectRoot, '.claude', 'agents'),
+        skills: path.join(projectRoot, '.claude', 'skills'),
+        commands: path.join(projectRoot, '.claude', 'commands'),
+        hooks: path.join(projectRoot, '.claude', 'hooks'),
+      };
+    case 'cursor':
+      return {
+        agents: path.join(projectRoot, '.cursor', 'agents'),
+        skills: path.join(projectRoot, '.cursor', 'skills'),
+        commands: path.join(projectRoot, '.cursor', 'commands'),
+        hooks: null,
+      };
+    default:
+      throw new Error(`Unknown target: ${target}`);
+  }
+}
+
+/**
+ * Load install manifests from the plugin root.
+ */
+function loadManifests(pluginRoot) {
+  const profilesPath = path.join(pluginRoot, 'manifests', 'install-profiles.json');
+  const modulesPath = path.join(pluginRoot, 'manifests', 'install-modules.json');
+
+  const profilesData = readJson(profilesPath);
+  const modulesData = readJson(modulesPath);
+
+  if (!profilesData) throw new Error(`Cannot read install-profiles.json at ${profilesPath}`);
+  if (!modulesData) throw new Error(`Cannot read install-modules.json at ${modulesPath}`);
+
+  // Extract nested profiles object from { version, profiles } wrapper
+  const profiles = profilesData.profiles || profilesData;
+
+  // Convert modules array to object keyed by id for lookup
+  const modulesArray = modulesData.modules || modulesData;
+  const modules = {};
+  if (Array.isArray(modulesArray)) {
+    for (const mod of modulesArray) {
+      if (mod.id) modules[mod.id] = mod;
+    }
+  } else {
+    Object.assign(modules, modulesArray);
+  }
+
+  return { profiles, modules, targets: {} };
+}
+
+/**
+ * Resolve which modules belong to a profile.
+ * @param {Object} profiles
+ * @param {string} profileName
+ * @returns {string[]} list of module names
+ */
+function resolveProfileModules(profiles, profileName, visited = new Set()) {
+  if (visited.has(profileName)) {
+    throw new Error(`Circular profile dependency detected: ${[...visited, profileName].join(' → ')}`);
+  }
+  const profile = profiles[profileName];
+  if (!profile) throw new Error(`Unknown profile: ${profileName}. Valid profiles: ${Object.keys(profiles).join(', ')}`);
+
+  visited.add(profileName);
+
+  // Profile may extend others
+  const moduleList = [];
+  if (profile.extends) {
+    for (const parent of (Array.isArray(profile.extends) ? profile.extends : [profile.extends])) {
+      moduleList.push(...resolveProfileModules(profiles, parent, new Set(visited)));
+    }
+  }
+  moduleList.push(...(profile.modules || []));
+
+  // Deduplicate while preserving order
+  return [...new Set(moduleList)];
+}
+
+/**
+ * Copy a single content file to the target directory.
+ * @returns {{ destPath: string, srcPath: string, module: string, hash: string } | null}
+ */
+function installFile(srcPath, destDir, relativeName, moduleName, dryRun) {
+  if (!fileExists(srcPath)) {
+    console.warn(`  [WARN] Source file not found: ${srcPath}`);
+    return null;
+  }
+
+  const destPath = path.join(destDir, relativeName);
+
+  if (dryRun) {
+    console.log(`  [dry-run] Would copy: ${srcPath} → ${destPath}`);
+    return { destPath, srcPath, module: moduleName, hash: simpleHash(srcPath) };
+  }
+
+  copyFile(srcPath, destPath);
+  return { destPath, srcPath, module: moduleName, hash: simpleHash(srcPath) };
+}
+
+/**
+ * Check if a source path is a skill directory (contains SKILL.md).
+ */
+function isSkillDir(srcPath) {
+  return fs.existsSync(path.join(srcPath, 'SKILL.md'));
+}
+
+/**
+ * Check if a source path is an agent file (agents/*.md).
+ */
+function isAgentFile(srcRelative) {
+  return srcRelative.startsWith('agents/') && srcRelative.endsWith('.md');
+}
+
+/**
+ * Install paths for a given source list to a target directory.
+ * @param {string} targetName - install target ('claude' or 'cursor')
+ * @returns {Array} installed file records
+ */
+function installPaths(pathsList, destDir, pluginRoot, moduleName, dryRun, targetName) {
+  const installed = [];
+
+  for (const srcRelative of pathsList) {
+    const srcPath = path.join(pluginRoot, srcRelative);
+
+    if (srcRelative.endsWith('/')) {
+      // Directory path — copy all files, preserving subdirectory name
+      if (!fs.existsSync(srcPath)) {
+        console.warn(`  [WARN] Source dir not found: ${srcPath}`);
+        continue;
+      }
+
+      const dirName = path.basename(srcRelative.slice(0, -1));
+      const destSubDir = path.join(destDir, dirName);
+
+      // Use skill adapter for Cursor target when source is a skill directory
+      if (targetName === 'cursor' && isSkillDir(srcPath)) {
+        if (dryRun) {
+          console.log(`  [dry-run] Would transform skill: ${srcRelative} → ${path.relative(pluginRoot, destSubDir)}/`);
+        } else {
+          transformSkillDir(srcPath, destSubDir);
+        }
+        installed.push({ destPath: destSubDir, srcPath, module: moduleName, hash: null });
+        continue;
+      }
+
+      const entries = fs.readdirSync(srcPath);
+      for (const entry of entries) {
+        const fullSrc = path.join(srcPath, entry);
+        if (fs.statSync(fullSrc).isFile()) {
+          const record = installFile(fullSrc, destSubDir, entry, moduleName, dryRun);
+          if (record) installed.push(record);
+        }
+      }
+    } else {
+      // Specific file path — use agent adapter for Cursor target
+      if (targetName === 'cursor' && isAgentFile(srcRelative)) {
+        const destPath = path.join(destDir, path.basename(srcRelative));
+        if (dryRun) {
+          console.log(`  [dry-run] Would transform agent: ${srcRelative} → ${path.relative(pluginRoot, destPath)}`);
+        } else {
+          transformAgentFile(srcPath, destPath);
+        }
+        installed.push({ destPath, srcPath, module: moduleName, hash: null });
+      } else {
+        const record = installFile(srcPath, destDir, path.basename(srcRelative), moduleName, dryRun);
+        if (record) installed.push(record);
+      }
+    }
+  }
+
+  return installed;
+}
+
+/**
+ * Install files for a single module definition.
+ * Supports two formats:
+ *   - Legacy: `paths` + `targets` (single target directory for all paths)
+ *   - Bundle: `pathGroups` array of { paths, targets } (different targets per content type)
+ *
+ * @param {Object} moduleDef - from install-modules.json
+ * @param {string} moduleName
+ * @param {string} pluginRoot
+ * @param {string} targetName - e.g. 'claude', 'cursor'
+ * @param {string} projectRoot
+ * @param {boolean} dryRun
+ * @returns {Array} installed file records
+ */
+function installModule(moduleDef, moduleName, pluginRoot, targetName, projectRoot, dryRun) {
+  // Bundle format: pathGroups array with per-group targets
+  if (Array.isArray(moduleDef.pathGroups)) {
+    const installed = [];
+    let hasAnyTarget = false;
+
+    for (const group of moduleDef.pathGroups) {
+      const destRelative = (group.targets || {})[targetName];
+      if (!destRelative) continue;
+      hasAnyTarget = true;
+      const destDir = path.join(projectRoot, destRelative);
+      installed.push(...installPaths(group.paths || [], destDir, pluginRoot, moduleName, dryRun, targetName));
+    }
+
+    if (!hasAnyTarget) {
+      console.log(`  [SKIP] Module ${moduleName} doesn't support target: ${targetName}`);
+    }
+    return installed;
+  }
+
+  // Legacy format: single paths + targets
+  const installed = [];
+  const destRelative = (moduleDef.targets || {})[targetName];
+  if (!destRelative) {
+    console.log(`  [SKIP] Module ${moduleName} doesn't support target: ${targetName}`);
+    return installed;
+  }
+
+  const destDir = path.join(projectRoot, destRelative);
+  return installPaths(moduleDef.paths || [], destDir, pluginRoot, moduleName, dryRun, targetName);
+}
+
+/**
+ * Execute a full installation.
+ *
+ * @param {string} profileName - e.g. 'full', 'apex', 'core'
+ * @param {string} targetName  - e.g. 'claude', 'cursor'
+ * @param {Object} options
+ * @param {boolean} [options.dryRun=false]
+ * @param {string}  [options.projectRoot=process.cwd()]
+ * @param {string}  [options.pluginRoot]
+ * @returns {{ installedFiles: Array, moduleCount: number, fileCount: number }}
+ */
+function executeInstall(profileName, targetName, options = {}) {
+  const dryRun = options.dryRun || false;
+  const projectRoot = options.projectRoot || process.cwd();
+  const pluginRoot = options.pluginRoot || process.env.CLAUDE_PLUGIN_ROOT || process.env.SCC_PLUGIN_ROOT || path.join(__dirname, '..', '..');
+
+  if (!VALID_TARGETS.includes(targetName)) {
+    throw new Error(`Invalid target: ${targetName}. Valid targets: ${VALID_TARGETS.join(', ')}`);
+  }
+  if (!VALID_PROFILES.includes(profileName)) {
+    throw new Error(`Invalid profile: ${profileName}. Valid profiles: ${VALID_PROFILES.join(', ')}`);
+  }
+
+  const { profiles, modules } = loadManifests(pluginRoot);
+  const moduleNames = resolveProfileModules(profiles, profileName);
+
+  console.log(`\nInstalling SCC — profile: ${profileName}, target: ${targetName}${dryRun ? ' [DRY RUN]' : ''}`);
+  console.log(`Project root: ${projectRoot}`);
+  console.log(`Modules to install: ${moduleNames.join(', ')}\n`);
+
+  const allInstalled = [];
+
+  for (const moduleName of moduleNames) {
+    const moduleDef = modules[moduleName];
+    if (!moduleDef) {
+      console.warn(`[WARN] Module definition not found: ${moduleName}`);
+      continue;
+    }
+    console.log(`Installing module: ${moduleName}`);
+    const records = installModule(moduleDef, moduleName, pluginRoot, targetName, projectRoot, dryRun);
+    allInstalled.push(...records);
+    console.log(`  ${records.length} file(s) installed`);
+  }
+
+  // Install MCP config (renamed file — claude: .mcp.json at root, cursor: .cursor/mcp.json)
+  const mcpSrc = path.join(pluginRoot, 'mcp-configs', 'mcp-servers.json');
+  const mcpDestMap = { claude: '.mcp.json', cursor: path.join('.cursor', 'mcp.json') };
+  const mcpDest = mcpDestMap[targetName];
+  if (mcpDest && fileExists(mcpSrc)) {
+    const destPath = path.join(projectRoot, mcpDest);
+    if (dryRun) {
+      console.log(`\nMCP config:`);
+      console.log(`  [dry-run] Would copy: mcp-configs/mcp-servers.json → ${mcpDest}`);
+    } else {
+      copyFile(mcpSrc, destPath);
+      console.log(`\nMCP config:`);
+      console.log(`  [OK] mcp-configs/mcp-servers.json → ${mcpDest}`);
+    }
+    allInstalled.push({ destPath, srcPath: mcpSrc, module: 'core', hash: simpleHash(mcpSrc) });
+  }
+
+  if (!dryRun) {
+    saveState({
+      profile: profileName,
+      target: targetName,
+      installedFiles: allInstalled,
+    });
+  }
+
+  console.log(`\n${dryRun ? '[DRY RUN] Would install' : 'Installed'} ${allInstalled.length} file(s) across ${moduleNames.length} module(s).`);
+
+  return {
+    installedFiles: allInstalled,
+    moduleCount: moduleNames.length,
+    fileCount: allInstalled.length,
+  };
+}
+
+/**
+ * List available install targets.
+ * @returns {string[]}
+ */
+function listAvailableTargets() {
+  return [...VALID_TARGETS];
+}
+
+/**
+ * List available install profiles.
+ * @param {string} [pluginRoot]
+ * @returns {Object} profile definitions
+ */
+function listAvailableProfiles(pluginRoot) {
+  const root = pluginRoot || process.env.CLAUDE_PLUGIN_ROOT || process.env.SCC_PLUGIN_ROOT || path.join(__dirname, '..', '..');
+  try {
+    const { profiles } = loadManifests(root);
+    return profiles;
+  } catch {
+    // Return defaults if manifests not yet created
+    return {
+      core: { description: 'Minimal baseline', modules: [] },
+      apex: { description: 'Apex development suite', modules: [] },
+      lwc: { description: 'LWC development suite', modules: [] },
+      devops: { description: 'DevOps and deployment', modules: [] },
+      security: { description: 'Security-focused', modules: [] },
+      full: { description: 'Complete suite', extends: ['apex', 'lwc', 'devops', 'security'], modules: [] },
+    };
+  }
+}
+
+module.exports = {
+  executeInstall,
+  listAvailableTargets,
+  listAvailableProfiles,
+  getTargetDirs,
+  resolveProfileModules,
+  VALID_TARGETS,
+  VALID_PROFILES,
+};

package/scripts/lib/install-state.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * install-state.js — Schema-validated install state tracking for SCC.
+ *
+ * Validates against schemas/install-state.schema.json on every read/write.
+ * Tracks rich installation provenance: target, request, resolution, source, operations.
+ *
+ * State is written to ~/.scc/install-state.json (separate from state.json).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { validateAgainstSchema, assertAgainstSchema, formatErrors } = require('./schema-validator');
+
+const STATE_DIR = path.join(os.homedir(), '.scc');
+const INSTALL_STATE_PATH = path.join(STATE_DIR, 'install-state.json');
+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schemas', 'install-state.schema.json');
+
+function ensureStateDir() {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+}
+
+/**
+ * Create a new install state object with all required fields.
+ *
+ * @param {Object} params
+ * @param {Object} params.target - { id, root, installStatePath, target?, kind? }
+ * @param {Object} params.request - { profile, modules, includeComponents, excludeComponents, legacyLanguages, legacyMode }
+ * @param {Object} params.resolution - { selectedModules, skippedModules }
+ * @param {Object} params.source - { repoVersion, repoCommit, manifestVersion }
+ * @param {Array}  params.operations - array of { kind, moduleId, sourceRelativePath, destinationPath, strategy, ownership, scaffoldOnly }
+ * @returns {Object} validated install state
+ */
+function createInstallState({ target, request, resolution, source, operations }) {
+  const state = {
+    schemaVersion: 'scc.install.v1',
+    installedAt: new Date().toISOString(),
+    target: {
+      id: target.id || 'default',
+      root: target.root || process.cwd(),
+      installStatePath: target.installStatePath || INSTALL_STATE_PATH,
+      ...(target.target ? { target: target.target } : {}),
+      ...(target.kind ? { kind: target.kind } : {}),
+    },
+    request: {
+      profile: request.profile || null,
+      modules: request.modules || [],
+      includeComponents: request.includeComponents || [],
+      excludeComponents: request.excludeComponents || [],
+      legacyLanguages: request.legacyLanguages || [],
+      legacyMode: request.legacyMode || false,
+    },
+    resolution: {
+      selectedModules: resolution.selectedModules || [],
+      skippedModules: resolution.skippedModules || [],
+    },
+    source: {
+      repoVersion: source.repoVersion || null,
+      repoCommit: source.repoCommit || null,
+      manifestVersion: source.manifestVersion || 2,
+    },
+    operations: (operations || []).map(op => ({
+      kind: op.kind || 'copy',
+      moduleId: op.moduleId || '',
+      sourceRelativePath: op.sourceRelativePath || '',
+      destinationPath: op.destinationPath || '',
+      strategy: op.strategy || 'overwrite',
+      ownership: op.ownership || 'scc',
+      scaffoldOnly: op.scaffoldOnly || false,
+    })),
+  };
+
+  assertAgainstSchema(SCHEMA_PATH, state, 'install-state');
+  return state;
+}
+
+/**
+ * Read install state from disk. Returns validated state or null if not found.
+ *
+ * @param {string} [statePath] - path to install state file (defaults to ~/.scc/install-state.json)
+ * @returns {Object|null} validated install state or null
+ */
+function readInstallState(statePath) {
+  const filePath = statePath || INSTALL_STATE_PATH;
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const state = JSON.parse(raw);
+
+    const result = validateAgainstSchema(SCHEMA_PATH, state);
+    if (!result.valid) {
+      process.stderr.write(`[SCC] install-state validation warning: ${formatErrors(result.errors)}\n`);
+      return null;
+    }
+
+    return state;
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      process.stderr.write(`[SCC] Failed to read install-state: ${err.message}\n`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Write install state to disk after validation.
+ *
+ * @param {string} [statePath] - path to write (defaults to ~/.scc/install-state.json)
+ * @param {Object} state - install state object (will be validated)
+ */
+function writeInstallState(state, statePath) {
+  assertAgainstSchema(SCHEMA_PATH, state, 'install-state');
+
+  const filePath = statePath || INSTALL_STATE_PATH;
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf8');
+}
+
+module.exports = { createInstallState, readInstallState, writeInstallState, INSTALL_STATE_PATH };