msd-core/src/runtime-config-adapter-registry.cts

'use strict';

/**
 * Runtime config adapter registry — dispatch table for install-phase config
 * mutations (issue #60), replacing inline `runtime === '...'` branching in
 * bin/install.js.
 *
 * ADR-857 phase 5g drive 2: The hand-kept REGISTRY const has been retired.
 * Values are now read directly from the capability-registry.cjs descriptor
 * (capabilities/<id>/capability.json runtime block) so a single source of
 * truth drives all surfaces.
 *
 * Design notes:
 * - `installSurface` selects which config handler install() runs:
 *     'settings-json'        → fall through to the shared settings.json accumulation.
 *     'codex-toml'           → early-return after writing codex.toml.
 *     'copilot-instructions' → early-return after writing .github/copilot-instructions.md.
 *     'cline-rules'          → early-return after writing .clinerules.
 *     'cursor-hooks-json'    → early-return after writing .cursor/hooks.json (issue #777).
 *     'profile-marker-only'  → early-return after writing only the profile marker.
 * - `writesSharedSettings` is the finishInstall writeSettings gate:
 *     false for codex / copilot / kilo / cursor / windsurf / trae / cline / kimi (legacy exclusion list).
 *     true for all other runtimes.
 * - `finishPermissionWriter` names the finishInstall-phase dedicated config writer:
 *     'opencode' → writes BOTH shared settings AND its own permissions file.
 *     'kilo'     → writes only its own permissions file.
 *     null       → no dedicated permission writer.
 */

// eslint-disable-next-line @typescript-eslint/no-require-imports
const { runtimes } = require('./capability-registry.cjs') as { runtimes: Record<string, { runtime: Record<string, unknown> | undefined }> };

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

type ConfigInstallSurface =
  | 'settings-json'
  | 'codex-toml'
  | 'copilot-instructions'
  | 'cline-rules'
  | 'cursor-hooks-json'
  | 'profile-marker-only';

type FinishPermissionWriter = 'opencode' | 'kilo' | null;

type HooksSurface =
  | 'settings-json'
  | 'codex-hooks-json'
  | 'cursor-hooks-json'
  | 'cline-rules'
  | 'copilot-inline'
  | 'none';

interface RuntimeConfigIntent {
  runtime: string;
  installSurface: ConfigInstallSurface;
  writesSharedSettings: boolean;
  finishPermissionWriter: FinishPermissionWriter;
}

/**
 * The full install plan for a runtime: config-intent axes PLUS the three
 * hook axes that install() reads from the capability descriptor.
 * ADR-857 phase 5g capstone — single seam for all install-level descriptor reads.
 */
interface InstallPlan extends RuntimeConfigIntent {
  /** Hook event dialect: 'claude' | 'gemini' | undefined */
  hookEvents: string | undefined;
  /** Extended hook event names registered beyond the core tool events (may be empty). */
  extendedHookEvents: string[];
  /** Which surface owns the hook registration for this runtime. */
  hooksSurface: HooksSurface;
}

// ---------------------------------------------------------------------------
// Exports
// ---------------------------------------------------------------------------

/** The complete set of 16 supported runtimes for config-adapter dispatch. */
const ALLOWED_CONFIG_RUNTIMES: ReadonlySet<string> = new Set(
  Object.entries(runtimes)
    .filter(([, cap]) => cap && cap.runtime && typeof cap.runtime['installSurface'] === 'string')
    .map(([id]) => id),
);

/** All valid installSurface values. */
const INSTALL_SURFACES: ReadonlyArray<ConfigInstallSurface> = Object.freeze([
  'settings-json',
  'codex-toml',
  'copilot-instructions',
  'cline-rules',
  'cursor-hooks-json',
  'profile-marker-only',
]);

/**
 * Resolve the config adapter intent for a given runtime.
 *
 * Returns a fresh object each call so callers cannot poison the registry by
 * mutating the returned value.
 *
 * @throws {TypeError} if runtime is not a known supported runtime.
 */
function resolveRuntimeConfigIntent(runtime: string): RuntimeConfigIntent {
  const entry = runtimes[runtime]?.runtime;
  if (!entry) throw new TypeError(`Unknown runtime for config adapter: ${runtime}`);
  const permissionWriter = entry['permissionWriter'];
  return {
    runtime,
    installSurface:         entry['installSurface'] as ConfigInstallSurface,
    writesSharedSettings:   entry['writesSharedSettings'] as boolean,
    finishPermissionWriter: permissionWriter == null ? null : permissionWriter as FinishPermissionWriter,
  };
}

/**
 * Resolve the complete install plan for a given runtime.
 *
 * Composes the config-intent axes from resolveRuntimeConfigIntent PLUS the
 * three hook axes (hookEvents / extendedHookEvents / hooksSurface) that
 * install() previously read scattered from the capability registry.
 *
 * ADR-857 phase 5g capstone — single typed seam for all install-level
 * descriptor reads. Returns a fresh object each call.
 *
 * @throws {TypeError} if runtime is not a known supported runtime.
 */
function resolveInstallPlan(runtime: string): InstallPlan {
  const desc = runtimes[runtime]?.runtime;
  if (!desc) throw new TypeError(`Unknown runtime for install plan: ${runtime}`);
  const configIntent = resolveRuntimeConfigIntent(runtime);
  return {
    runtime,
    installSurface:         configIntent.installSurface,
    writesSharedSettings:   configIntent.writesSharedSettings,
    finishPermissionWriter: configIntent.finishPermissionWriter,
    hookEvents:             desc['hookEvents'] as string | undefined,
    extendedHookEvents:     Array.isArray(desc['extendedHookEvents']) ? desc['extendedHookEvents'] as string[] : [],
    hooksSurface:           desc['hooksSurface'] != null
      ? desc['hooksSurface'] as HooksSurface
      : ((runtime === 'opencode' || runtime === 'kilo') ? 'none' : 'settings-json'),
  };
}

export = { resolveRuntimeConfigIntent, resolveInstallPlan, ALLOWED_CONFIG_RUNTIMES, INSTALL_SURFACES };