claudex-setup 1.7.0 → 1.8.0

package/src/domain-packs.js

@@ -0,0 +1,160 @@
+const DOMAIN_PACKS = [
+  {
+    key: 'baseline-general',
+    label: 'Baseline General',
+    useWhen: 'General repos that need a pragmatic Claude baseline without domain-specific assumptions.',
+    recommendedModules: ['CLAUDE.md baseline', 'verification', 'safe-write profile'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['discover next actions', 'starter-safe improvement', 'governed rollout'],
+  },
+  {
+    key: 'backend-api',
+    label: 'Backend API',
+    useWhen: 'Service, API, or backend-heavy repos with routes, services, jobs, or data access.',
+    recommendedModules: ['verification', 'security workflow', 'commands', 'rules'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['test + build verification', 'security review workflow', 'safe apply on existing config'],
+  },
+  {
+    key: 'frontend-ui',
+    label: 'Frontend UI',
+    useWhen: 'React, Next.js, Vue, Angular, or Svelte repos with components and UI-heavy workflows.',
+    recommendedModules: ['frontend rules', 'design guidance', 'commands', 'benchmark'],
+    recommendedMcpPacks: ['context7-docs', 'next-devtools'],
+    benchmarkFocus: ['build checks', 'component workflow quality', 'framework-aware starter output'],
+  },
+  {
+    key: 'data-pipeline',
+    label: 'Data Pipeline',
+    useWhen: 'Repos with workers, DAGs, marts, ETL jobs, migrations, or analytics-heavy workflows.',
+    recommendedModules: ['verification', 'rules', 'agents', 'benchmark'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['pipeline safety', 'repeatable task flows', 'state-aware review artifacts'],
+  },
+  {
+    key: 'infra-platform',
+    label: 'Infra Platform',
+    useWhen: 'Terraform, Docker, Kubernetes, Wrangler, or deployment-oriented repos.',
+    recommendedModules: ['ci-devops', 'commands', 'governance', 'benchmark'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['release safety', 'policy-controlled rollout', 'infra verification loops'],
+  },
+  {
+    key: 'oss-library',
+    label: 'OSS Library',
+    useWhen: 'Public packages or contributor-heavy repos that need a lighter governance footprint.',
+    recommendedModules: ['suggest-only profile', 'light rules', 'commands', 'README-aligned CLAUDE.md'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['low-footprint adoption', 'manual review friendliness', 'contributor-safe defaults'],
+  },
+  {
+    key: 'enterprise-governed',
+    label: 'Enterprise Governed',
+    useWhen: 'Repos with CI, permissions, hooks, and a need for auditable change controls.',
+    recommendedModules: ['governance', 'activity artifacts', 'rollback manifests', 'benchmark evidence'],
+    recommendedMcpPacks: ['context7-docs'],
+    benchmarkFocus: ['policy-aware rollout', 'approval flow readiness', 'benchmark export quality'],
+  },
+];
+
+function uniqueByKey(items) {
+  const seen = new Set();
+  const result = [];
+  for (const item of items) {
+    if (seen.has(item.key)) continue;
+    seen.add(item.key);
+    result.push(item);
+  }
+  return result;
+}
+
+function detectDomainPacks(ctx, stacks, assets = null) {
+  const stackKeys = new Set((stacks || []).map(stack => stack.key));
+  const pkg = ctx.jsonFile('package.json') || {};
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const matches = [];
+
+  function addMatch(key, reasons) {
+    const pack = DOMAIN_PACKS.find(item => item.key === key);
+    if (!pack) return;
+    matches.push({
+      ...pack,
+      matchReasons: reasons.filter(Boolean).slice(0, 3),
+    });
+  }
+
+  const hasFrontend = stackKeys.has('react') || stackKeys.has('nextjs') || stackKeys.has('vue') ||
+    stackKeys.has('angular') || stackKeys.has('svelte') || ctx.hasDir('components') || ctx.hasDir('app') || ctx.hasDir('pages');
+  const hasBackend = stackKeys.has('node') || stackKeys.has('python') || stackKeys.has('django') ||
+    stackKeys.has('fastapi') || stackKeys.has('go') || stackKeys.has('rust') || stackKeys.has('java') ||
+    ctx.hasDir('api') || ctx.hasDir('routes') || ctx.hasDir('services') || ctx.hasDir('controllers');
+  const hasData = ctx.hasDir('dags') || ctx.hasDir('jobs') || ctx.hasDir('workers') ||
+    ctx.hasDir('models') || ctx.hasDir('migrations') || ctx.hasDir('db') ||
+    deps.dbt || deps['apache-airflow'] || deps.pandas || deps.polars || deps.duckdb;
+  const hasInfra = stackKeys.has('docker') || stackKeys.has('terraform') || stackKeys.has('kubernetes') ||
+    ctx.files.includes('wrangler.toml') || ctx.files.includes('serverless.yml') || ctx.files.includes('serverless.yaml') ||
+    ctx.files.includes('cdk.json') || ctx.hasDir('infra') || ctx.hasDir('deploy') || ctx.hasDir('helm');
+  const isOss = !!ctx.fileContent('LICENSE') && !!ctx.fileContent('CONTRIBUTING.md') && pkg.private !== true;
+  const isEnterpriseGoverned = !!(assets && assets.permissions && assets.permissions.hasDenyRules) &&
+    !!(assets && assets.files && assets.files.settings) && ctx.hasDir('.github/workflows');
+
+  if (hasBackend) {
+    addMatch('backend-api', [
+      'Detected backend stack or service directories.',
+      ctx.hasDir('api') ? 'API-facing structure detected.' : null,
+      ctx.hasDir('services') ? 'Service-layer directories detected.' : null,
+    ]);
+  }
+
+  if (hasFrontend) {
+    addMatch('frontend-ui', [
+      'Detected frontend stack or UI directories.',
+      ctx.hasDir('components') ? 'Component directories detected.' : null,
+      stackKeys.has('nextjs') ? 'Next.js stack detected.' : null,
+    ]);
+  }
+
+  if (hasData) {
+    addMatch('data-pipeline', [
+      'Detected worker, jobs, models, or analytics-style structure.',
+      ctx.hasDir('jobs') ? 'Job/pipeline directories detected.' : null,
+      ctx.hasDir('migrations') ? 'Migration flow detected.' : null,
+    ]);
+  }
+
+  if (hasInfra) {
+    addMatch('infra-platform', [
+      'Detected deployment or infrastructure signals.',
+      ctx.files.includes('wrangler.toml') ? 'Wrangler deployment config detected.' : null,
+      ctx.hasDir('deploy') ? 'Deployment directory detected.' : null,
+    ]);
+  }
+
+  if (isOss) {
+    addMatch('oss-library', [
+      'License and contribution guidance suggest an open-source repo.',
+      pkg.private === false ? 'package.json is not marked private.' : null,
+    ]);
+  }
+
+  if (isEnterpriseGoverned) {
+    addMatch('enterprise-governed', [
+      'Settings, deny rules, and CI indicate a governed team workflow.',
+      'Repo already has policy-aware Claude assets.',
+    ]);
+  }
+
+  const deduped = uniqueByKey(matches);
+  if (deduped.length === 0) {
+    return [{
+      ...DOMAIN_PACKS.find(item => item.key === 'baseline-general'),
+      matchReasons: ['No stronger domain signal detected yet.'],
+    }];
+  }
+  return deduped;
+}
+
+module.exports = {
+  DOMAIN_PACKS,
+  detectDomainPacks,
+};

package/src/governance.js

@@ -1,3 +1,6 @@
+const { DOMAIN_PACKS } = require('./domain-packs');
+const { MCP_PACKS, mergeMcpServers, normalizeMcpPackKeys } = require('./mcp-packs');
+
 const PERMISSION_PROFILES = [
   {
     key: 'read-only',
@@ -137,11 +140,147 @@ const PILOT_ROLLOUT_KIT = {
   ],
 };
 
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function mergeUnique(existing = [], additions = []) {
+  return [...new Set([...(Array.isArray(existing) ? existing : []), ...additions])];
+}
+
+function mergeHooks(existingHooks = {}, nextHooks = {}) {
+  const merged = clone(existingHooks || {});
+
+  for (const [stage, blocks] of Object.entries(nextHooks)) {
+    const targetBlocks = Array.isArray(merged[stage]) ? clone(merged[stage]) : [];
+    for (const incoming of blocks) {
+      const index = targetBlocks.findIndex(block => block.matcher === incoming.matcher);
+      if (index === -1) {
+        targetBlocks.push(clone(incoming));
+        continue;
+      }
+
+      const current = targetBlocks[index];
+      const existingCommands = new Set((current.hooks || []).map(hook => `${hook.type}:${hook.command}:${hook.timeout || ''}`));
+      const mergedHooks = [...(current.hooks || [])];
+      for (const hook of incoming.hooks || []) {
+        const signature = `${hook.type}:${hook.command}:${hook.timeout || ''}`;
+        if (!existingCommands.has(signature)) {
+          mergedHooks.push(clone(hook));
+          existingCommands.add(signature);
+        }
+      }
+      targetBlocks[index] = { ...current, hooks: mergedHooks };
+    }
+    merged[stage] = targetBlocks;
+  }
+
+  return merged;
+}
+
+function getPermissionProfile(key = 'safe-write') {
+  return PERMISSION_PROFILES.find(profile => profile.key === key) ||
+    PERMISSION_PROFILES.find(profile => profile.key === 'safe-write');
+}
+
+function isWritableProfile(key = 'safe-write') {
+  return ['safe-write', 'power-user', 'internal-research'].includes(getPermissionProfile(key).key);
+}
+
+function ensureWritableProfile(key = 'safe-write', commandName = 'apply', dryRun = false) {
+  const profile = getPermissionProfile(key);
+  if (!dryRun && !isWritableProfile(profile.key)) {
+    throw new Error(`${commandName} requires a writable profile. Use --profile safe-write or --dry-run.`);
+  }
+  return profile;
+}
+
+function buildHookConfig(hookFiles, profileKey) {
+  const profile = getPermissionProfile(profileKey);
+  if (!isWritableProfile(profile.key)) {
+    return {};
+  }
+
+  const uniqueFiles = [...new Set(hookFiles)].sort();
+  if (uniqueFiles.length === 0) {
+    return {};
+  }
+
+  const hookConfig = {
+    PostToolUse: [{
+      matcher: 'Write|Edit',
+      hooks: uniqueFiles
+        .filter(file => file !== 'protect-secrets.sh' && file !== 'session-start.sh')
+        .map(file => ({
+          type: 'command',
+          command: `bash .claude/hooks/${file}`,
+          timeout: 10,
+        })),
+    }],
+  };
+
+  if (uniqueFiles.includes('protect-secrets.sh')) {
+    hookConfig.PreToolUse = [{
+      matcher: 'Read|Write|Edit',
+      hooks: [{
+        type: 'command',
+        command: 'bash .claude/hooks/protect-secrets.sh',
+        timeout: 5,
+      }],
+    }];
+  }
+
+  if (uniqueFiles.includes('session-start.sh')) {
+    hookConfig.SessionStart = [{
+      matcher: '*',
+      hooks: [{
+        type: 'command',
+        command: 'bash .claude/hooks/session-start.sh',
+        timeout: 5,
+      }],
+    }];
+  }
+
+  if ((hookConfig.PostToolUse[0].hooks || []).length === 0) {
+    delete hookConfig.PostToolUse;
+  }
+
+  return hookConfig;
+}
+
+function buildSettingsForProfile({ profileKey = 'safe-write', hookFiles = [], existingSettings = null, mcpPackKeys = [] } = {}) {
+  const profile = getPermissionProfile(profileKey);
+  const base = existingSettings ? clone(existingSettings) : {};
+  const selectedMcpPacks = normalizeMcpPackKeys(mcpPackKeys);
+  base.permissions = base.permissions || {};
+  base.permissions.defaultMode = profile.defaultMode;
+  base.permissions.deny = mergeUnique(base.permissions.deny, profile.deny);
+
+  const hookConfig = buildHookConfig(hookFiles, profile.key);
+  if (Object.keys(hookConfig).length > 0) {
+    base.hooks = mergeHooks(base.hooks, hookConfig);
+  }
+
+  if (selectedMcpPacks.length > 0) {
+    base.mcpServers = mergeMcpServers(base.mcpServers, selectedMcpPacks);
+  }
+
+  base.claudexSetup = {
+    ...(base.claudexSetup || {}),
+    profile: profile.key,
+    mcpPacks: selectedMcpPacks,
+  };
+
+  return base;
+}
+
 function getGovernanceSummary() {
   return {
     permissionProfiles: PERMISSION_PROFILES,
     hookRegistry: HOOK_REGISTRY,
     policyPacks: POLICY_PACKS,
+    domainPacks: DOMAIN_PACKS,
+    mcpPacks: MCP_PACKS,
     pilotRolloutKit: PILOT_ROLLOUT_KIT,
   };
 }
@@ -179,6 +318,18 @@ function printGovernanceSummary(summary, options = {}) {
   }
   console.log('');
 
+  console.log('  Domain Packs');
+  for (const pack of summary.domainPacks) {
+    console.log(`  - ${pack.label}: ${pack.useWhen}`);
+  }
+  console.log('');
+
+  console.log('  MCP Packs');
+  for (const pack of summary.mcpPacks) {
+    console.log(`  - ${pack.label}: ${Object.keys(pack.servers).join(', ')}`);
+  }
+  console.log('');
+
   console.log('  Pilot Rollout Kit');
   for (const item of summary.pilotRolloutKit.recommendedScope) {
     console.log(`  - ${item}`);
@@ -187,6 +338,11 @@ function printGovernanceSummary(summary, options = {}) {
 }
 
 module.exports = {
+  PERMISSION_PROFILES,
+  getPermissionProfile,
+  isWritableProfile,
+  ensureWritableProfile,
+  buildSettingsForProfile,
   getGovernanceSummary,
   printGovernanceSummary,
 };

package/src/index.js

@@ -4,6 +4,8 @@ const { analyzeProject } = require('./analyze');
 const { buildProposalBundle, applyProposalBundle } = require('./plans');
 const { getGovernanceSummary } = require('./governance');
 const { runBenchmark } = require('./benchmark');
+const { DOMAIN_PACKS, detectDomainPacks } = require('./domain-packs');
+const { MCP_PACKS, getMcpPack, mergeMcpServers, recommendMcpPacks } = require('./mcp-packs');
 
 module.exports = {
   audit,
@@ -13,4 +15,10 @@ module.exports = {
   applyProposalBundle,
   getGovernanceSummary,
   runBenchmark,
+  DOMAIN_PACKS,
+  detectDomainPacks,
+  MCP_PACKS,
+  getMcpPack,
+  mergeMcpServers,
+  recommendMcpPacks,
 };

package/src/mcp-packs.js

@@ -0,0 +1,85 @@
+const MCP_PACKS = [
+  {
+    key: 'context7-docs',
+    label: 'Context7 Docs',
+    useWhen: 'Repos that benefit from live, current framework and library documentation during Claude sessions.',
+    adoption: 'Safe default docs pack for most application repos.',
+    servers: {
+      context7: {
+        command: 'npx',
+        args: ['-y', '@upstash/context7-mcp@latest'],
+      },
+    },
+  },
+  {
+    key: 'next-devtools',
+    label: 'Next.js Devtools',
+    useWhen: 'Next.js repos that need runtime-aware debugging and framework-specific tooling.',
+    adoption: 'Useful companion pack for frontend-ui repos running Next.js.',
+    servers: {
+      'next-devtools': {
+        command: 'npx',
+        args: ['-y', 'next-devtools-mcp@latest'],
+      },
+    },
+  },
+];
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function getMcpPack(key) {
+  return MCP_PACKS.find(pack => pack.key === key) || null;
+}
+
+function normalizeMcpPackKeys(keys = []) {
+  return [...new Set((Array.isArray(keys) ? keys : [])
+    .map(key => `${key}`.trim())
+    .filter(Boolean))]
+    .filter(key => !!getMcpPack(key));
+}
+
+function mergeMcpServers(existing = {}, packKeys = []) {
+  const merged = clone(existing || {});
+  for (const key of normalizeMcpPackKeys(packKeys)) {
+    const pack = getMcpPack(key);
+    if (!pack) continue;
+    for (const [serverName, serverConfig] of Object.entries(pack.servers || {})) {
+      if (!merged[serverName]) {
+        merged[serverName] = clone(serverConfig);
+      }
+    }
+  }
+  return merged;
+}
+
+function recommendMcpPacks(stacks = [], domainPacks = []) {
+  const recommended = new Set();
+  const stackKeys = new Set(stacks.map(stack => stack.key));
+
+  for (const pack of domainPacks) {
+    for (const key of pack.recommendedMcpPacks || []) {
+      recommended.add(key);
+    }
+  }
+
+  if (stackKeys.has('nextjs')) {
+    recommended.add('next-devtools');
+  }
+  if (stackKeys.size > 0) {
+    recommended.add('context7-docs');
+  }
+
+  return MCP_PACKS
+    .filter(pack => recommended.has(pack.key))
+    .map(pack => clone(pack));
+}
+
+module.exports = {
+  MCP_PACKS,
+  getMcpPack,
+  normalizeMcpPackKeys,
+  mergeMcpServers,
+  recommendMcpPacks,
+};