claudecode-omc 5.5.2 → 5.6.0

package/src/catalog/source-catalog.js

@@ -0,0 +1,391 @@
+const fs = require('fs');
+const path = require('path');
+const { readConfig } = require('../config/sources');
+const { getProjectRoot, getSourceArtifactDir, getSourceMetadataDir, getSourceRootDir } = require('../config/paths');
+const { loadSkillsFromSource } = require('../merge/skill-merger');
+const { loadAgentsFromSource } = require('../merge/agent-merger');
+const { loadCommandsFromSource } = require('../merge/command-merger');
+const { loadHookFilesFromSource } = require('../merge/hook-merger');
+const { filterItemsByAllowlist } = require('../config/sources');
+
+const KNOWN_ARTIFACT_TYPES = new Set(['skills', 'agents', 'hooks', 'commands', 'guidelines', 'settings', 'hud', 'claude-md']);
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function parseSimpleYaml(content) {
+  const result = {};
+  let currentListKey = null;
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.replace(/\t/g, '  ');
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const listMatch = line.match(/^\s*-\s+(.*)$/);
+    if (listMatch && currentListKey) {
+      result[currentListKey].push(listMatch[1].trim().replace(/^['"]|['"]$/g, ''));
+      continue;
+    }
+
+    const keyMatch = line.match(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+    if (!keyMatch) continue;
+
+    const [, key, value] = keyMatch;
+    if (!value) {
+      currentListKey = key;
+      result[key] = [];
+      continue;
+    }
+
+    currentListKey = null;
+    result[key] = value.trim().replace(/^['"]|['"]$/g, '');
+  }
+
+  return result;
+}
+
+function safeReadText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function manifestTypeForPath(manifestPath) {
+  if (manifestPath.endsWith('package.json')) return 'package.json';
+  if (manifestPath.endsWith('plugin.json')) return 'plugin.json';
+  if (manifestPath.endsWith('.yaml') || manifestPath.endsWith('.yml')) return 'yaml';
+  return 'text';
+}
+
+function parseManifestDocument(filePath, manifestPath) {
+  const type = manifestTypeForPath(manifestPath);
+  if (type === 'package.json' || type === 'plugin.json') {
+    return safeReadJson(filePath);
+  }
+  if (type === 'yaml') {
+    const content = safeReadText(filePath);
+    return content ? parseSimpleYaml(content) : null;
+  }
+  return safeReadText(filePath);
+}
+
+function countSurfaceEntries(surfacePath) {
+  if (!fs.existsSync(surfacePath)) return 0;
+  const stat = fs.statSync(surfacePath);
+  if (stat.isFile()) return 1;
+  return fs.readdirSync(surfacePath).length;
+}
+
+function getArtifactLoader(artifactType) {
+  switch (artifactType) {
+    case 'skills': return loadSkillsFromSource;
+    case 'agents': return loadAgentsFromSource;
+    case 'commands': return loadCommandsFromSource;
+    case 'hooks': return loadHookFilesFromSource;
+    default: return null;
+  }
+}
+
+function classifyPackageFile(entry) {
+  const [topLevel] = entry.split('/');
+  switch (topLevel) {
+    case '.claude':
+    case '.claude-plugin':
+      return { name: topLevel, harness: 'claude', category: 'manifest', installable: false, adapter: 'claude-plugin-adapter' };
+    case '.codex':
+    case '.codex-plugin':
+      return { name: topLevel, harness: 'codex', category: 'harness-surface', installable: false, adapter: 'harness-dir-adapter' };
+    case '.cursor':
+      return { name: topLevel, harness: 'cursor', category: 'harness-surface', installable: false, adapter: 'harness-dir-adapter' };
+    case '.gemini':
+      return { name: topLevel, harness: 'gemini', category: 'harness-surface', installable: false, adapter: 'harness-dir-adapter' };
+    case '.opencode':
+      return { name: topLevel, harness: 'opencode', category: 'harness-surface', installable: false, adapter: 'harness-dir-adapter' };
+    case 'rules':
+      return { name: topLevel, harness: 'generic', category: 'reference', installable: false, adapter: 'rules-adapter' };
+    case 'mcp-configs':
+      return { name: topLevel, harness: 'generic', category: 'tooling', installable: false, adapter: 'mcp-config-adapter' };
+    case 'schemas':
+    case 'manifests':
+      return { name: topLevel, harness: 'generic', category: 'manifest', installable: false, adapter: 'manifest-adapter' };
+    case 'scripts':
+      return { name: topLevel, harness: 'generic', category: 'tooling', installable: false, adapter: 'tooling-script-adapter' };
+    case 'skills':
+    case 'agents':
+    case 'hooks':
+    case 'commands':
+      return { name: topLevel, harness: 'claude', category: 'runtime', installable: true, artifactType: topLevel, adapter: 'flat-dir-adapter' };
+    default:
+      return null;
+  }
+}
+
+function upsertSurface(surfaces, nextSurface) {
+  const key = [nextSurface.name, nextSurface.harness, nextSurface.category, nextSurface.artifactType || ''].join('::');
+  const existing = surfaces.get(key);
+  if (!existing) {
+    surfaces.set(key, { ...nextSurface });
+    return;
+  }
+
+  existing.present = existing.present || nextSurface.present;
+  existing.installable = existing.installable || nextSurface.installable;
+  existing.count = Math.max(existing.count || 0, nextSurface.count || 0);
+  existing.adapter = existing.adapter || nextSurface.adapter;
+  existing.sources = [...new Set([...(existing.sources || []), ...(nextSurface.sources || [])])];
+}
+
+function listManifestFiles(sourceName, sourceConfig, root) {
+  const sourceRoot = getSourceRootDir(sourceName, root);
+  const metadataDir = getSourceMetadataDir(sourceName, root);
+
+  return (sourceConfig.manifests || []).map((manifestPath) => {
+    const localCandidate = path.join(sourceRoot, manifestPath);
+    const cachedCandidate = path.join(metadataDir, 'manifests', manifestPath);
+    const filePath = fs.existsSync(localCandidate) ? localCandidate : cachedCandidate;
+    const present = fs.existsSync(filePath);
+    return {
+      path: manifestPath,
+      filePath,
+      present,
+      type: manifestTypeForPath(manifestPath),
+      data: present ? parseManifestDocument(filePath, manifestPath) : null,
+    };
+  });
+}
+
+async function buildSourceCatalog(sourceName, root = getProjectRoot()) {
+  const config = readConfig();
+  const sourceConfig = config.sources[sourceName];
+  if (!sourceConfig) {
+    throw new Error(`Unknown source: ${sourceName}`);
+  }
+
+  const manifests = listManifestFiles(sourceName, sourceConfig, root);
+  const surfaces = new Map();
+  const warnings = [];
+
+  for (const artifactType of sourceConfig.artifacts || []) {
+    const artifactPath = getSourceArtifactDir(sourceName, artifactType, root);
+    const present = fs.existsSync(artifactPath);
+    const loader = getArtifactLoader(artifactType);
+    const loadedItems = (present && loader)
+      ? filterItemsByAllowlist(sourceConfig, artifactType, loader(artifactPath, sourceName))
+      : [];
+    upsertSurface(surfaces, {
+      name: artifactType,
+      harness: 'claude',
+      category: KNOWN_ARTIFACT_TYPES.has(artifactType) ? 'runtime' : 'unknown',
+      artifactType,
+      // `installable` describes intrinsic capability so `plan install` can
+      // model transitions out of role=reference. Actual install gating lives
+      // in setup.js/artifact.js (role + installMode checks).
+      installable: KNOWN_ARTIFACT_TYPES.has(artifactType),
+      count: loader ? loadedItems.length : (present ? countSurfaceEntries(artifactPath) : 0),
+      itemNames: loadedItems.length > 0 ? loadedItems.map(item => item.name).sort() : undefined,
+      present,
+      sourcePath: artifactPath,
+      adapter: 'flat-dir-adapter',
+      sources: ['config.artifacts'],
+    });
+  }
+
+  for (const manifest of manifests) {
+    if (!manifest.present) {
+      warnings.push(`Manifest not found: ${manifest.path}`);
+      continue;
+    }
+
+    if (manifest.path.endsWith('package.json') && manifest.data && Array.isArray(manifest.data.files)) {
+      for (const fileEntry of manifest.data.files) {
+        const classified = classifyPackageFile(fileEntry);
+        if (!classified) continue;
+        if (classified.artifactType && (sourceConfig.artifacts || []).includes(classified.artifactType)) {
+          continue;
+        }
+        upsertSurface(surfaces, {
+          ...classified,
+          count: 1,
+          present: true,
+          sourcePath: fileEntry,
+          sources: ['package.json'],
+        });
+      }
+    }
+
+    if (manifest.path.endsWith('plugin.json') && manifest.data) {
+      const pluginData = manifest.data;
+      if (Array.isArray(pluginData.skills) && pluginData.skills.length > 0) {
+        upsertSurface(surfaces, {
+          name: 'skills',
+          harness: 'claude',
+          category: 'runtime',
+          artifactType: 'skills',
+          installable: true,
+          count: pluginData.skills.length,
+          present: true,
+          sourcePath: manifest.path,
+          adapter: 'claude-plugin-adapter',
+          sources: ['plugin.json'],
+        });
+      }
+      if (Array.isArray(pluginData.commands) && pluginData.commands.length > 0) {
+        upsertSurface(surfaces, {
+          name: 'commands',
+          harness: 'claude',
+          category: 'runtime',
+          artifactType: 'commands',
+          installable: true,
+          count: pluginData.commands.length,
+          present: true,
+          sourcePath: manifest.path,
+          adapter: 'claude-plugin-adapter',
+          sources: ['plugin.json'],
+        });
+      }
+    }
+
+    if ((manifest.path.endsWith('agent.yaml') || manifest.path.endsWith('agent.yml')) && manifest.data) {
+      const yamlData = manifest.data;
+      for (const key of ['skills', 'commands']) {
+        if (Array.isArray(yamlData[key]) && yamlData[key].length > 0) {
+          upsertSurface(surfaces, {
+            name: key,
+            harness: 'claude',
+            category: key === 'skills' || key === 'commands' ? 'runtime' : 'manifest',
+            artifactType: key,
+            installable: key === 'skills' || key === 'commands',
+            count: yamlData[key].length,
+            present: true,
+            sourcePath: manifest.path,
+            adapter: 'catalog-manifest-adapter',
+            sources: ['agent.yaml'],
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    sourceName,
+    kind: sourceConfig.kind || 'content-repo',
+    installMode: sourceConfig.installMode || 'auto',
+    role: sourceConfig.role || null,
+    harnesses: sourceConfig.harnesses || ['claude'],
+    profiles: sourceConfig.profiles || ['claude-runtime', 'reference-only'],
+    manifests,
+    surfaces: [...surfaces.values()].sort((a, b) => a.name.localeCompare(b.name) || a.harness.localeCompare(b.harness)),
+    warnings,
+  };
+}
+
+function buildInstallPlan(catalog, profileName = 'claude-runtime') {
+  const supportedProfiles = new Set(catalog.profiles || []);
+  if (!supportedProfiles.has(profileName)) {
+    throw new Error(`Profile "${profileName}" is not declared for source "${catalog.sourceName}"`);
+  }
+
+  let selected;
+  if (profileName === 'claude-runtime') {
+    selected = catalog.surfaces.filter(surface => (
+      surface.category === 'runtime'
+      && surface.harness === 'claude'
+      && surface.installable
+      && (surface.count || 0) > 0
+    ));
+  } else if (profileName === 'reference-only') {
+    selected = catalog.surfaces.filter(surface => surface.category !== 'runtime' || !surface.installable);
+  } else {
+    selected = catalog.surfaces.filter(surface => surface.present);
+  }
+
+  const selectedKeys = new Set(selected.map(surface => [surface.name, surface.harness, surface.category].join('::')));
+  const skipped = catalog.surfaces.filter(surface => !selectedKeys.has([surface.name, surface.harness, surface.category].join('::')));
+
+  const actions = selected.map((surface) => {
+    if (surface.category === 'runtime' && surface.artifactType) {
+      return {
+        type: 'install-artifact',
+        artifactType: surface.artifactType,
+        adapter: surface.adapter || 'flat-dir-adapter',
+        source: surface.sourcePath,
+        count: surface.count || 0,
+        itemNames: surface.itemNames || [],
+      };
+    }
+
+    return {
+      type: 'reference-surface',
+      surface: surface.name,
+      adapter: surface.adapter || null,
+      source: surface.sourcePath,
+      count: surface.count || 0,
+    };
+  });
+
+  const warnings = [...catalog.warnings];
+  if (catalog.kind === 'distribution-repo') {
+    const nonClaude = catalog.surfaces.filter(surface => surface.harness !== 'claude' && surface.present);
+    if (nonClaude.length > 0 && profileName === 'claude-runtime') {
+      warnings.push(`Skipped ${nonClaude.length} non-Claude harness surfaces for profile "${profileName}".`);
+    }
+  }
+
+  return {
+    sourceName: catalog.sourceName,
+    kind: catalog.kind,
+    installMode: catalog.installMode,
+    profile: profileName,
+    actions,
+    selectedSurfaces: selected,
+    skippedSurfaces: skipped,
+    warnings,
+  };
+}
+
+function deriveSourceActivation(planResult, currentSource = {}) {
+  const installArtifacts = [...new Set(
+    planResult.actions
+      .filter(action => action.type === 'install-artifact' && action.artifactType)
+      .map(action => action.artifactType),
+  )];
+
+  if (planResult.profile === 'reference-only') {
+    // Preserve the discoverable artifact list so the source can round-trip back
+    // to claude-runtime later. setup.js/artifact.js already gate installation on
+    // role==='reference' and installMode!=='auto', so retaining artifacts here
+    // does not risk accidental install.
+    const preserved = Array.isArray(currentSource.artifacts) && currentSource.artifacts.length > 0
+      ? [...currentSource.artifacts]
+      : installArtifacts;
+    return {
+      installMode: 'planned',
+      role: 'reference',
+      artifacts: preserved,
+      allowlist: undefined,
+      appliedProfile: planResult.profile,
+    };
+  }
+
+  return {
+    installMode: 'auto',
+    role: null,
+    artifacts: installArtifacts,
+    allowlist: undefined,
+    appliedProfile: planResult.profile,
+  };
+}
+
+module.exports = {
+  buildSourceCatalog,
+  buildInstallPlan,
+  deriveSourceActivation,
+};

package/src/cli/artifact.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const fsp = require('fs/promises');
 const path = require('path');
 const { getProjectRoot, getSourceArtifactDir, getMergeConfigPath, getReportDir } = require('../config/paths');
-const { readConfig } = require('../config/sources');
+const { readConfig, filterItemsByAllowlist } = require('../config/sources');
 const { ARTIFACT_TYPES, getArtifactTypeNames } = require('../config/artifact-types');
 const { detectConflicts, resolveConflicts, applyResolutions, generateReport } = require('../merge/base-merger');
 const { loadSkillsFromSource } = require('../merge/skill-merger');
@@ -49,10 +49,11 @@ function loadSourcesForType(artifactType, root) {
 
   for (const [name, src] of ordered) {
     if (src.role === 'reference') continue;
+    if (src.installMode && src.installMode !== 'auto') continue;
     if (!(src.artifacts || []).includes(artifactType)) continue;
     const dir = getSourceArtifactDir(name, artifactType, root);
     if (!fs.existsSync(dir)) continue;
-    const items = loader(dir, name);
+    const items = filterItemsByAllowlist(src, artifactType, loader(dir, name));
     if (items.length > 0) {
       sources.push({ name, items });
     }

package/src/cli/doctor.js

@@ -56,16 +56,37 @@ async function doctor() {
       const dir = getSourceArtifactDir(name, type, root);
       return fs.existsSync(dir);
     });
-    const status = name === 'local'
-      ? `${available.length}/${artifacts.length} types present`
-      : `${available.length}/${artifacts.length} types synced`;
-    check(`${name} (priority ${src.priority})`, () => {
+
+    const isPlanned = src.installMode && src.installMode !== 'auto';
+    const isReference = src.role === 'reference';
+    const tagBits = [`priority ${src.priority}`, `kind ${src.kind || 'content-repo'}`];
+    if (isPlanned) tagBits.push(`installMode ${src.installMode}`);
+    if (isReference) tagBits.push('role reference');
+    if (src.appliedProfile) tagBits.push(`profile ${src.appliedProfile}`);
+
+    if (isPlanned && !isReference) {
+      // Distribution-repo waiting for plan apply: surface it without claiming
+      // failure — sync may have already populated catalog manifests.
+      console.log(`  ○ ${name} (${tagBits.join(', ')}) — staged, run "omc-manage plan apply ${name}" to activate`);
+      if (available.length > 0) {
+        console.log(`    synced types: ${available.join(', ')}`);
+      }
+      continue;
+    }
+
+    check(`${name} (${tagBits.join(', ')})`, () => {
       return available.length > 0 ? true : 'not synced';
     });
     if (available.length > 0 && available.length < artifacts.length) {
       const missing = artifacts.filter(t => !available.includes(t));
       console.log(`    missing: ${missing.join(', ')}`);
     }
+    if (src.allowlist && Object.keys(src.allowlist).length > 0) {
+      const allowlist = Object.entries(src.allowlist)
+        .map(([type, names]) => `${type}(${names.length})`)
+        .join(', ');
+      console.log(`    allowlist: ${allowlist}`);
+    }
   }
 
   console.log('');

package/src/cli/index.js

@@ -4,6 +4,7 @@ const COMMANDS = {
   setup: () => require('./setup'),
   doctor: () => require('./doctor'),
   source: () => require('./source'),
+  plan: () => require('./plan'),
   skill: () => require('./skill'),
   artifact: () => require('./artifact'),
   guidelines: () => require('./guidelines'),
@@ -19,6 +20,9 @@ function showHelp() {
   console.log('            Install merged artifacts (skills, agents, hooks, commands, etc.)');
   console.log('  doctor    Health checks for all artifact types');
   console.log('  source    list|add|remove|sync|status — manage sources');
+  console.log('            inspect <name> — inspect source bundle/catalog');
+  console.log('  plan      install <source> [--profile <name>] — build install plan');
+  console.log('            apply <source> [--profile <name>] — materialize plan into source activation');
   console.log('  artifact  list|prefer|conflicts [--type <type>] — manage artifacts');
   console.log('  guidelines optimize [source...] [--output-dir <dir>] [--dry-run]');
   console.log('  guidelines apply --result-file <path> [--output-dir <dir>] [--dry-run]');
@@ -79,10 +83,25 @@ async function main(argv) {
     else if (arg.startsWith('--mapping=')) flags.mapping = arg.split('=')[1];
     else if (arg === '--role' && args[i + 1]) flags.role = args[++i];
     else if (arg.startsWith('--role=')) flags.role = arg.split('=')[1];
+    else if (arg === '--kind' && args[i + 1]) flags.kind = args[++i];
+    else if (arg.startsWith('--kind=')) flags.kind = arg.split('=')[1];
+    else if (arg === '--install-mode' && args[i + 1]) flags.installMode = args[++i];
+    else if (arg.startsWith('--install-mode=')) flags.installMode = arg.split('=')[1];
+    else if (arg === '--harnesses' && args[i + 1]) flags.harnesses = args[++i].split(',');
+    else if (arg.startsWith('--harnesses=')) flags.harnesses = arg.split('=')[1].split(',');
+    else if (arg === '--manifests' && args[i + 1]) flags.manifests = args[++i].split(',');
+    else if (arg.startsWith('--manifests=')) flags.manifests = arg.split('=')[1].split(',');
+    else if (arg === '--profiles' && args[i + 1]) flags.profiles = args[++i].split(',');
+    else if (arg.startsWith('--profiles=')) flags.profiles = arg.split('=')[1].split(',');
     else if (arg === '--output-dir' && args[i + 1]) flags.outputDir = args[++i];
     else if (arg.startsWith('--output-dir=')) flags.outputDir = arg.split('=')[1];
     else if (arg === '--result-file' && args[i + 1]) flags.resultFile = args[++i];
     else if (arg.startsWith('--result-file=')) flags.resultFile = arg.split('=')[1];
+    else if (arg === '--selection-file' && args[i + 1]) flags.selectionFile = args[++i];
+    else if (arg.startsWith('--selection-file=')) flags.selectionFile = arg.split('=')[1];
+    else if (arg === '--profile' && args[i + 1]) flags.profile = args[++i];
+    else if (arg.startsWith('--profile=')) flags.profile = arg.split('=')[1];
+    else if (arg === '--json') flags.json = true;
     else if (arg === '--apply') flags.apply = true;
     else if (arg === '--threshold' && args[i + 1]) flags.threshold = args[++i];
     else if (arg.startsWith('--threshold=')) flags.threshold = arg.split('=')[1];