cc4pm 1.8.0

package/scripts/lib/install-manifests.js

@@ -0,0 +1,305 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { planInstallTargetScaffold } = require('./install-targets/registry');
+
+const DEFAULT_REPO_ROOT = path.join(__dirname, '../..');
+const SUPPORTED_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity', 'codex', 'opencode'];
+const COMPONENT_FAMILY_PREFIXES = {
+  baseline: 'baseline:',
+  language: 'lang:',
+  framework: 'framework:',
+  capability: 'capability:',
+};
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to read ${label}: ${error.message}`);
+  }
+}
+
+function dedupeStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : []).map(value => String(value).trim()).filter(Boolean))];
+}
+
+function intersectTargets(modules) {
+  if (!Array.isArray(modules) || modules.length === 0) {
+    return [];
+  }
+
+  return SUPPORTED_INSTALL_TARGETS.filter(target => (
+    modules.every(module => Array.isArray(module.targets) && module.targets.includes(target))
+  ));
+}
+
+function getManifestPaths(repoRoot = DEFAULT_REPO_ROOT) {
+  return {
+    modulesPath: path.join(repoRoot, 'manifests', 'install-modules.json'),
+    profilesPath: path.join(repoRoot, 'manifests', 'install-profiles.json'),
+    componentsPath: path.join(repoRoot, 'manifests', 'install-components.json'),
+  };
+}
+
+function loadInstallManifests(options = {}) {
+  const repoRoot = options.repoRoot || DEFAULT_REPO_ROOT;
+  const { modulesPath, profilesPath, componentsPath } = getManifestPaths(repoRoot);
+
+  if (!fs.existsSync(modulesPath) || !fs.existsSync(profilesPath)) {
+    throw new Error(`Install manifests not found under ${repoRoot}`);
+  }
+
+  const modulesData = readJson(modulesPath, 'install-modules.json');
+  const profilesData = readJson(profilesPath, 'install-profiles.json');
+  const componentsData = fs.existsSync(componentsPath)
+    ? readJson(componentsPath, 'install-components.json')
+    : { version: null, components: [] };
+  const modules = Array.isArray(modulesData.modules) ? modulesData.modules : [];
+  const profiles = profilesData && typeof profilesData.profiles === 'object'
+    ? profilesData.profiles
+    : {};
+  const components = Array.isArray(componentsData.components) ? componentsData.components : [];
+  const modulesById = new Map(modules.map(module => [module.id, module]));
+  const componentsById = new Map(components.map(component => [component.id, component]));
+
+  return {
+    repoRoot,
+    modulesPath,
+    profilesPath,
+    componentsPath,
+    modules,
+    profiles,
+    components,
+    modulesById,
+    componentsById,
+    modulesVersion: modulesData.version,
+    profilesVersion: profilesData.version,
+    componentsVersion: componentsData.version,
+  };
+}
+
+function listInstallProfiles(options = {}) {
+  const manifests = loadInstallManifests(options);
+  return Object.entries(manifests.profiles).map(([id, profile]) => ({
+    id,
+    description: profile.description,
+    moduleCount: Array.isArray(profile.modules) ? profile.modules.length : 0,
+  }));
+}
+
+function listInstallModules(options = {}) {
+  const manifests = loadInstallManifests(options);
+  return manifests.modules.map(module => ({
+    id: module.id,
+    kind: module.kind,
+    description: module.description,
+    targets: module.targets,
+    defaultInstall: module.defaultInstall,
+    cost: module.cost,
+    stability: module.stability,
+    dependencyCount: Array.isArray(module.dependencies) ? module.dependencies.length : 0,
+  }));
+}
+
+function listInstallComponents(options = {}) {
+  const manifests = loadInstallManifests(options);
+  const family = options.family || null;
+  const target = options.target || null;
+
+  if (family && !Object.hasOwn(COMPONENT_FAMILY_PREFIXES, family)) {
+    throw new Error(
+      `Unknown component family: ${family}. Expected one of ${Object.keys(COMPONENT_FAMILY_PREFIXES).join(', ')}`
+    );
+  }
+
+  if (target && !SUPPORTED_INSTALL_TARGETS.includes(target)) {
+    throw new Error(
+      `Unknown install target: ${target}. Expected one of ${SUPPORTED_INSTALL_TARGETS.join(', ')}`
+    );
+  }
+
+  return manifests.components
+    .filter(component => !family || component.family === family)
+    .map(component => {
+      const moduleIds = dedupeStrings(component.modules);
+      const modules = moduleIds
+        .map(moduleId => manifests.modulesById.get(moduleId))
+        .filter(Boolean);
+      const targets = intersectTargets(modules);
+
+      return {
+        id: component.id,
+        family: component.family,
+        description: component.description,
+        moduleIds,
+        moduleCount: moduleIds.length,
+        targets,
+      };
+    })
+    .filter(component => !target || component.targets.includes(target));
+}
+
+function expandComponentIdsToModuleIds(componentIds, manifests) {
+  const expandedModuleIds = [];
+
+  for (const componentId of dedupeStrings(componentIds)) {
+    const component = manifests.componentsById.get(componentId);
+    if (!component) {
+      throw new Error(`Unknown install component: ${componentId}`);
+    }
+    expandedModuleIds.push(...component.modules);
+  }
+
+  return dedupeStrings(expandedModuleIds);
+}
+
+function resolveInstallPlan(options = {}) {
+  const manifests = loadInstallManifests(options);
+  const profileId = options.profileId || null;
+  const explicitModuleIds = dedupeStrings(options.moduleIds);
+  const includedComponentIds = dedupeStrings(options.includeComponentIds);
+  const excludedComponentIds = dedupeStrings(options.excludeComponentIds);
+  const requestedModuleIds = [];
+
+  if (profileId) {
+    const profile = manifests.profiles[profileId];
+    if (!profile) {
+      throw new Error(`Unknown install profile: ${profileId}`);
+    }
+    requestedModuleIds.push(...profile.modules);
+  }
+
+  requestedModuleIds.push(...explicitModuleIds);
+  requestedModuleIds.push(...expandComponentIdsToModuleIds(includedComponentIds, manifests));
+
+  const excludedModuleIds = expandComponentIdsToModuleIds(excludedComponentIds, manifests);
+  const excludedModuleOwners = new Map();
+  for (const componentId of excludedComponentIds) {
+    const component = manifests.componentsById.get(componentId);
+    if (!component) {
+      throw new Error(`Unknown install component: ${componentId}`);
+    }
+    for (const moduleId of component.modules) {
+      const owners = excludedModuleOwners.get(moduleId) || [];
+      owners.push(componentId);
+      excludedModuleOwners.set(moduleId, owners);
+    }
+  }
+
+  const target = options.target || null;
+  if (target && !SUPPORTED_INSTALL_TARGETS.includes(target)) {
+    throw new Error(
+      `Unknown install target: ${target}. Expected one of ${SUPPORTED_INSTALL_TARGETS.join(', ')}`
+    );
+  }
+
+  const effectiveRequestedIds = dedupeStrings(
+    requestedModuleIds.filter(moduleId => !excludedModuleOwners.has(moduleId))
+  );
+
+  if (requestedModuleIds.length === 0) {
+    throw new Error('No install profile, module IDs, or included component IDs were provided');
+  }
+
+  if (effectiveRequestedIds.length === 0) {
+    throw new Error('Selection excludes every requested install module');
+  }
+
+  const selectedIds = new Set();
+  const skippedTargetIds = new Set();
+  const excludedIds = new Set(excludedModuleIds);
+  const visitingIds = new Set();
+  const resolvedIds = new Set();
+
+  function resolveModule(moduleId, dependencyOf) {
+    const module = manifests.modulesById.get(moduleId);
+    if (!module) {
+      throw new Error(`Unknown install module: ${moduleId}`);
+    }
+
+    if (excludedModuleOwners.has(moduleId)) {
+      if (dependencyOf) {
+        const owners = excludedModuleOwners.get(moduleId) || [];
+        throw new Error(
+          `Module ${dependencyOf} depends on excluded module ${moduleId}${owners.length > 0 ? ` (excluded by ${owners.join(', ')})` : ''}`
+        );
+      }
+      return;
+    }
+
+    if (target && !module.targets.includes(target)) {
+      if (dependencyOf) {
+        throw new Error(
+          `Module ${dependencyOf} depends on ${moduleId}, which does not support target ${target}`
+        );
+      }
+      skippedTargetIds.add(moduleId);
+      return;
+    }
+
+    if (resolvedIds.has(moduleId)) {
+      return;
+    }
+
+    if (visitingIds.has(moduleId)) {
+      throw new Error(`Circular install dependency detected at ${moduleId}`);
+    }
+
+    visitingIds.add(moduleId);
+    for (const dependencyId of module.dependencies) {
+      resolveModule(dependencyId, moduleId);
+    }
+    visitingIds.delete(moduleId);
+    resolvedIds.add(moduleId);
+    selectedIds.add(moduleId);
+  }
+
+  for (const moduleId of effectiveRequestedIds) {
+    resolveModule(moduleId, null);
+  }
+
+  const selectedModules = manifests.modules.filter(module => selectedIds.has(module.id));
+  const skippedModules = manifests.modules.filter(module => skippedTargetIds.has(module.id));
+  const excludedModules = manifests.modules.filter(module => excludedIds.has(module.id));
+  const scaffoldPlan = target
+    ? planInstallTargetScaffold({
+      target,
+      repoRoot: manifests.repoRoot,
+      projectRoot: options.projectRoot || manifests.repoRoot,
+      homeDir: options.homeDir || os.homedir(),
+      modules: selectedModules,
+    })
+    : null;
+
+  return {
+    repoRoot: manifests.repoRoot,
+    profileId,
+    target,
+    requestedModuleIds: effectiveRequestedIds,
+    explicitModuleIds,
+    includedComponentIds,
+    excludedComponentIds,
+    selectedModuleIds: selectedModules.map(module => module.id),
+    skippedModuleIds: skippedModules.map(module => module.id),
+    excludedModuleIds: excludedModules.map(module => module.id),
+    selectedModules,
+    skippedModules,
+    excludedModules,
+    targetAdapterId: scaffoldPlan ? scaffoldPlan.adapter.id : null,
+    targetRoot: scaffoldPlan ? scaffoldPlan.targetRoot : null,
+    installStatePath: scaffoldPlan ? scaffoldPlan.installStatePath : null,
+    operations: scaffoldPlan ? scaffoldPlan.operations : [],
+  };
+}
+
+module.exports = {
+  DEFAULT_REPO_ROOT,
+  SUPPORTED_INSTALL_TARGETS,
+  getManifestPaths,
+  loadInstallManifests,
+  listInstallComponents,
+  listInstallModules,
+  listInstallProfiles,
+  resolveInstallPlan,
+};

package/scripts/lib/install-state.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+
+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schemas', 'install-state.schema.json');
+
+let cachedValidator = null;
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to read ${label}: ${error.message}`);
+  }
+}
+
+function getValidator() {
+  if (cachedValidator) {
+    return cachedValidator;
+  }
+
+  const schema = readJson(SCHEMA_PATH, 'install-state schema');
+  const ajv = new Ajv({ allErrors: true });
+  cachedValidator = ajv.compile(schema);
+  return cachedValidator;
+}
+
+function formatValidationErrors(errors = []) {
+  return errors
+    .map(error => `${error.instancePath || '/'} ${error.message}`)
+    .join('; ');
+}
+
+function validateInstallState(state) {
+  const validator = getValidator();
+  const valid = validator(state);
+  return {
+    valid,
+    errors: validator.errors || [],
+  };
+}
+
+function assertValidInstallState(state, label) {
+  const result = validateInstallState(state);
+  if (!result.valid) {
+    throw new Error(`Invalid install-state${label ? ` (${label})` : ''}: ${formatValidationErrors(result.errors)}`);
+  }
+}
+
+function createInstallState(options) {
+  const installedAt = options.installedAt || new Date().toISOString();
+  const state = {
+    schemaVersion: 'ecc.install.v1',
+    installedAt,
+    target: {
+      id: options.adapter.id,
+      target: options.adapter.target || undefined,
+      kind: options.adapter.kind || undefined,
+      root: options.targetRoot,
+      installStatePath: options.installStatePath,
+    },
+    request: {
+      profile: options.request.profile || null,
+      modules: Array.isArray(options.request.modules) ? [...options.request.modules] : [],
+      includeComponents: Array.isArray(options.request.includeComponents)
+        ? [...options.request.includeComponents]
+        : [],
+      excludeComponents: Array.isArray(options.request.excludeComponents)
+        ? [...options.request.excludeComponents]
+        : [],
+      legacyLanguages: Array.isArray(options.request.legacyLanguages)
+        ? [...options.request.legacyLanguages]
+        : [],
+      legacyMode: Boolean(options.request.legacyMode),
+    },
+    resolution: {
+      selectedModules: Array.isArray(options.resolution.selectedModules)
+        ? [...options.resolution.selectedModules]
+        : [],
+      skippedModules: Array.isArray(options.resolution.skippedModules)
+        ? [...options.resolution.skippedModules]
+        : [],
+    },
+    source: {
+      repoVersion: options.source.repoVersion || null,
+      repoCommit: options.source.repoCommit || null,
+      manifestVersion: options.source.manifestVersion,
+    },
+    operations: Array.isArray(options.operations)
+      ? options.operations.map(operation => ({ ...operation }))
+      : [],
+  };
+
+  if (options.lastValidatedAt) {
+    state.lastValidatedAt = options.lastValidatedAt;
+  }
+
+  assertValidInstallState(state, 'create');
+  return state;
+}
+
+function readInstallState(filePath) {
+  const state = readJson(filePath, 'install-state');
+  assertValidInstallState(state, filePath);
+  return state;
+}
+
+function writeInstallState(filePath, state) {
+  assertValidInstallState(state, filePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`);
+  return state;
+}
+
+module.exports = {
+  createInstallState,
+  readInstallState,
+  validateInstallState,
+  writeInstallState,
+};

package/scripts/lib/install-targets/antigravity-project.js

@@ -0,0 +1,9 @@
+const { createInstallTargetAdapter } = require('./helpers');
+
+module.exports = createInstallTargetAdapter({
+  id: 'antigravity-project',
+  target: 'antigravity',
+  kind: 'project',
+  rootSegments: ['.agent'],
+  installStatePathSegments: ['ecc-install-state.json'],
+});

package/scripts/lib/install-targets/claude-home.js

@@ -0,0 +1,10 @@
+const { createInstallTargetAdapter } = require('./helpers');
+
+module.exports = createInstallTargetAdapter({
+  id: 'claude-home',
+  target: 'claude',
+  kind: 'home',
+  rootSegments: ['.claude'],
+  installStatePathSegments: ['ecc', 'install-state.json'],
+  nativeRootRelativePath: '.claude-plugin',
+});

package/scripts/lib/install-targets/codex-home.js

@@ -0,0 +1,10 @@
+const { createInstallTargetAdapter } = require('./helpers');
+
+module.exports = createInstallTargetAdapter({
+  id: 'codex-home',
+  target: 'codex',
+  kind: 'home',
+  rootSegments: ['.codex'],
+  installStatePathSegments: ['ecc-install-state.json'],
+  nativeRootRelativePath: '.codex',
+});

package/scripts/lib/install-targets/cursor-project.js

@@ -0,0 +1,10 @@
+const { createInstallTargetAdapter } = require('./helpers');
+
+module.exports = createInstallTargetAdapter({
+  id: 'cursor-project',
+  target: 'cursor',
+  kind: 'project',
+  rootSegments: ['.cursor'],
+  installStatePathSegments: ['ecc-install-state.json'],
+  nativeRootRelativePath: '.cursor',
+});

package/scripts/lib/install-targets/helpers.js

@@ -0,0 +1,89 @@
+const os = require('os');
+const path = require('path');
+
+function normalizeRelativePath(relativePath) {
+  return String(relativePath || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\/+/, '')
+    .replace(/\/+$/, '');
+}
+
+function resolveBaseRoot(scope, input = {}) {
+  if (scope === 'home') {
+    return input.homeDir || os.homedir();
+  }
+
+  if (scope === 'project') {
+    const projectRoot = input.projectRoot || input.repoRoot;
+    if (!projectRoot) {
+      throw new Error('projectRoot or repoRoot is required for project install targets');
+    }
+    return projectRoot;
+  }
+
+  throw new Error(`Unsupported install target scope: ${scope}`);
+}
+
+function createInstallTargetAdapter(config) {
+  const adapter = {
+    id: config.id,
+    target: config.target,
+    kind: config.kind,
+    nativeRootRelativePath: config.nativeRootRelativePath || null,
+    supports(target) {
+      return target === config.target || target === config.id;
+    },
+    resolveRoot(input = {}) {
+      const baseRoot = resolveBaseRoot(config.kind, input);
+      return path.join(baseRoot, ...config.rootSegments);
+    },
+    getInstallStatePath(input = {}) {
+      const root = adapter.resolveRoot(input);
+      return path.join(root, ...config.installStatePathSegments);
+    },
+    resolveDestinationPath(sourceRelativePath, input = {}) {
+      const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+      const targetRoot = adapter.resolveRoot(input);
+
+      if (
+        config.nativeRootRelativePath
+        && normalizedSourcePath === normalizeRelativePath(config.nativeRootRelativePath)
+      ) {
+        return targetRoot;
+      }
+
+      return path.join(targetRoot, normalizedSourcePath);
+    },
+    determineStrategy(sourceRelativePath) {
+      const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+
+      if (
+        config.nativeRootRelativePath
+        && normalizedSourcePath === normalizeRelativePath(config.nativeRootRelativePath)
+      ) {
+        return 'sync-root-children';
+      }
+
+      return 'preserve-relative-path';
+    },
+    createScaffoldOperation(moduleId, sourceRelativePath, input = {}) {
+      const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+      return {
+        kind: 'copy-path',
+        moduleId,
+        sourceRelativePath: normalizedSourcePath,
+        destinationPath: adapter.resolveDestinationPath(normalizedSourcePath, input),
+        strategy: adapter.determineStrategy(normalizedSourcePath),
+        ownership: 'managed',
+        scaffoldOnly: true,
+      };
+    },
+  };
+
+  return Object.freeze(adapter);
+}
+
+module.exports = {
+  createInstallTargetAdapter,
+  normalizeRelativePath,
+};

package/scripts/lib/install-targets/opencode-home.js

@@ -0,0 +1,10 @@
+const { createInstallTargetAdapter } = require('./helpers');
+
+module.exports = createInstallTargetAdapter({
+  id: 'opencode-home',
+  target: 'opencode',
+  kind: 'home',
+  rootSegments: ['.opencode'],
+  installStatePathSegments: ['ecc-install-state.json'],
+  nativeRootRelativePath: '.opencode',
+});

package/scripts/lib/install-targets/registry.js

@@ -0,0 +1,64 @@
+const antigravityProject = require('./antigravity-project');
+const claudeHome = require('./claude-home');
+const codexHome = require('./codex-home');
+const cursorProject = require('./cursor-project');
+const opencodeHome = require('./opencode-home');
+
+const ADAPTERS = Object.freeze([
+  claudeHome,
+  cursorProject,
+  antigravityProject,
+  codexHome,
+  opencodeHome,
+]);
+
+function listInstallTargetAdapters() {
+  return ADAPTERS.slice();
+}
+
+function getInstallTargetAdapter(targetOrAdapterId) {
+  const adapter = ADAPTERS.find(candidate => candidate.supports(targetOrAdapterId));
+
+  if (!adapter) {
+    throw new Error(`Unknown install target adapter: ${targetOrAdapterId}`);
+  }
+
+  return adapter;
+}
+
+function planInstallTargetScaffold(options = {}) {
+  const adapter = getInstallTargetAdapter(options.target);
+  const modules = Array.isArray(options.modules) ? options.modules : [];
+  const planningInput = {
+    repoRoot: options.repoRoot,
+    projectRoot: options.projectRoot || options.repoRoot,
+    homeDir: options.homeDir,
+  };
+  const targetRoot = adapter.resolveRoot(planningInput);
+  const installStatePath = adapter.getInstallStatePath(planningInput);
+  const operations = modules.flatMap(module => {
+    const paths = Array.isArray(module.paths) ? module.paths : [];
+    return paths.map(sourceRelativePath => adapter.createScaffoldOperation(
+      module.id,
+      sourceRelativePath,
+      planningInput
+    ));
+  });
+
+  return {
+    adapter: {
+      id: adapter.id,
+      target: adapter.target,
+      kind: adapter.kind,
+    },
+    targetRoot,
+    installStatePath,
+    operations,
+  };
+}
+
+module.exports = {
+  getInstallTargetAdapter,
+  listInstallTargetAdapters,
+  planInstallTargetScaffold,
+};