claude-dev-env 2.8.0 → 2.10.0

package/scripts/profile-isolation-launchers/launcher-runtime.mjs

@@ -0,0 +1,180 @@
+/**
+ * Launcher runtime helpers for MCP activation through a supported interface.
+ */
+
+import { join } from 'node:path';
+import {
+  CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE,
+  loadProfilesManifestDocument,
+  MCP_BUNDLE_FULL,
+  MCP_BUNDLE_LEAN,
+} from './config/profile-isolation-constants.mjs';
+import {
+  resolveProfileDefinition,
+  validateProfilesManifest,
+} from './lib/profile-manifest.mjs';
+import {
+  listServerNamesForBundle,
+  loadMcpBundlesDocument,
+  materializeProfileMcpConfig,
+  resolveProfileMcpBundleId,
+  SUPPORTED_ACTIVATION_INTERFACE,
+} from './mcp-bundles.mjs';
+import {
+  classifyVersionCompatibility,
+  shouldBlockLaunch,
+} from './version-compatibility.mjs';
+
+/**
+ * Resolve a launcher name to a profile id from the profiles manifest.
+ *
+ * @param {string} launcherName
+ * @returns {string}
+ */
+export function resolveProfileIdForLauncherName(launcherName) {
+  const manifest = validateProfilesManifest(loadProfilesManifestDocument());
+  try {
+    return resolveProfileDefinition(manifest, launcherName).id;
+  } catch (errorValue) {
+    if (
+      errorValue instanceof Error
+      && errorValue.message.startsWith('Unknown profile id or alias:')
+    ) {
+      throw new Error(`no profile owns launcher name: ${launcherName}`);
+    }
+    throw errorValue;
+  }
+}
+
+/**
+ * Assemble activation for one profile into a disposable CLAUDE_CONFIG_DIR.
+ *
+ * @param {{
+ *   profileId: string,
+ *   claudeConfigDir: string,
+ * }} parameters
+ * @returns {{
+ *   profileId: string,
+ *   environment: Record<string, string>,
+ *   activationInterface: string,
+ *   mcpConfigPath: string,
+ *   bundleId: string,
+ *   allServerNames: string[],
+ *   expectedInventory: string[],
+ * }}
+ */
+export function activateProfileMcpBundle(parameters) {
+  const bundlesDocument = loadMcpBundlesDocument();
+  const materialization = materializeProfileMcpConfig({
+    profileId: parameters.profileId,
+    claudeConfigDir: parameters.claudeConfigDir,
+    bundlesDocument,
+  });
+  const expectedInventory = [...materialization.allServerNames].sort();
+  return {
+    profileId: parameters.profileId,
+    environment: {
+      [CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE]: parameters.claudeConfigDir,
+    },
+    activationInterface: materialization.activationInterface,
+    mcpConfigPath: materialization.mcpConfigPath,
+    bundleId: materialization.bundleId,
+    allServerNames: materialization.allServerNames,
+    expectedInventory,
+  };
+}
+
+/**
+ * Activate MCP for a launcher name (claude-profile-a / claude-profile-b).
+ *
+ * @param {{
+ *   launcherName: string,
+ *   claudeConfigDir: string,
+ * }} parameters
+ * @returns {ReturnType<typeof activateProfileMcpBundle>}
+ */
+export function activateLauncherMcpBundle(parameters) {
+  const profileId = resolveProfileIdForLauncherName(parameters.launcherName);
+  return activateProfileMcpBundle({
+    profileId,
+    claudeConfigDir: parameters.claudeConfigDir,
+  });
+}
+
+/**
+ * Lean-boundary check: lean inventory is a subset of full and excludes full-only servers.
+ *
+ * @returns {{leanServers: string[], fullServers: string[], fullOnlyServers: string[]}}
+ */
+export function describeLeanServerBoundary() {
+  const bundlesDocument = loadMcpBundlesDocument();
+  const leanServers = listServerNamesForBundle(MCP_BUNDLE_LEAN, bundlesDocument).sort();
+  const fullServers = listServerNamesForBundle(MCP_BUNDLE_FULL, bundlesDocument).sort();
+  const leanSet = new Set(leanServers);
+  const fullOnlyServers = fullServers.filter((eachName) => !leanSet.has(eachName));
+  return { leanServers, fullServers, fullOnlyServers };
+}
+
+/**
+ * Build a diagnostic when a required bundle or profile is invalid.
+ *
+ * @param {string} profileId
+ * @param {unknown} errorValue
+ * @returns {string}
+ */
+export function formatProfileMcpActivationFailure(profileId, errorValue) {
+  const message = errorValue instanceof Error ? errorValue.message : String(errorValue);
+  return `profile ${profileId} mcp activation failed: ${message}`;
+}
+
+/**
+ * Evaluate CLI vs Desktop version compatibility from already-collected probes.
+ *
+ * Call this before any profile-state mutation. Spawn and binary discovery stay
+ * in the caller; this adapter only runs the shared classifier.
+ *
+ * @param {{
+ *   cli: import('./version-compatibility.mjs').VersionProbeResult,
+ *   desktop: import('./version-compatibility.mjs').VersionProbeResult,
+ * }} parameters
+ * @returns {import('./version-compatibility.mjs').CompatibilityResult}
+ */
+export function evaluateLauncherVersionCompatibility(parameters) {
+  return classifyVersionCompatibility(parameters);
+}
+
+/**
+ * Build a preflight failure message when compatibility blocks launch.
+ *
+ * @param {import('./version-compatibility.mjs').CompatibilityResult} result
+ * @returns {string}
+ */
+export function formatCompatibilityPreflightFailure(result) {
+  return `version compatibility preflight blocked launch (${result.class}): ${result.message}`;
+}
+
+/**
+ * Path helpers for tests and pack verification.
+ *
+ * @param {string} packageRoot
+ * @returns {string[]}
+ */
+export function listMcpActivationPackageRelativePaths(packageRoot) {
+  return [
+    join(packageRoot, 'scripts/profile-isolation-launchers/mcp-bundles.mjs'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/launcher-runtime.mjs'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/version-compatibility.mjs'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/config/mcp-bundles.json'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/config/profiles.manifest.json'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/tests/mcp-bundles.test.mjs'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/tests/launcher-runtime.test.mjs'),
+    join(packageRoot, 'scripts/profile-isolation-launchers/tests/version-compatibility.test.mjs'),
+  ];
+}
+
+export {
+  SUPPORTED_ACTIVATION_INTERFACE,
+  resolveProfileMcpBundleId,
+  classifyVersionCompatibility,
+  shouldBlockLaunch,
+};

package/scripts/profile-isolation-launchers/lib/profile-manifest.mjs

@@ -0,0 +1,288 @@
+import { join } from 'node:path';
+
+import {
+  LAUNCHER_SCHEMA_VERSION,
+  loadProfilesManifestDocument,
+  loadSharedAllowlistDocument,
+  MCP_BUNDLE_FULL,
+  MCP_BUNDLE_LEAN,
+  MIGRATION_MODE_CLEAN_LOCAL_RUNTIME,
+  MIGRATION_MODE_MATERIALIZE_FROM_LEGACY,
+} from '../config/profile-isolation-constants.mjs';
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   aliases: string[],
+ *   directoryName: string,
+ *   launcherNames: string[],
+ *   fullLauncherNames: string[],
+ *   migrationMode: string,
+ *   mcpBundle: string,
+ * }} ProfileDefinition
+ */
+
+/**
+ * @typedef {{
+ *   schemaVersion: number,
+ *   profilesRootPlaceholder: string,
+ *   sharedSourcePlaceholder: string,
+ *   pluginSeedPlaceholder: string,
+ *   migrationOrder: string[],
+ *   profileById: Record<string, ProfileDefinition>,
+ * }} ValidatedProfilesManifest
+ */
+
+/**
+ * @typedef {{
+ *   schemaVersion: number,
+ *   allSharedRelativePaths: string[],
+ *   allAlwaysLocalRelativePaths: string[],
+ *   allDesktopExcludedPathFragments: string[],
+ * }} ValidatedSharedAllowlist
+ */
+
+const ALL_ALLOWED_MIGRATION_MODES = new Set([
+  MIGRATION_MODE_CLEAN_LOCAL_RUNTIME,
+  MIGRATION_MODE_MATERIALIZE_FROM_LEGACY,
+]);
+
+const ALL_ALLOWED_MCP_BUNDLES = new Set([MCP_BUNDLE_LEAN, MCP_BUNDLE_FULL]);
+
+/**
+ * @param {unknown} maybeManifest
+ * @returns {ValidatedProfilesManifest}
+ */
+export function validateProfilesManifest(maybeManifest) {
+  if (!isPlainObject(maybeManifest)) {
+    throw new Error('profiles manifest must be a JSON object');
+  }
+  const schemaVersion = maybeManifest.schemaVersion;
+  if (schemaVersion !== LAUNCHER_SCHEMA_VERSION) {
+    throw new Error(`profiles manifest schemaVersion must be ${LAUNCHER_SCHEMA_VERSION}`);
+  }
+  if (!Array.isArray(maybeManifest.migrationOrder) || maybeManifest.migrationOrder.length === 0) {
+    throw new Error('profiles manifest migrationOrder must be a non-empty array');
+  }
+  if (!isPlainObject(maybeManifest.profiles)) {
+    throw new Error('profiles manifest profiles must be an object');
+  }
+  /** @type {Record<string, ProfileDefinition>} */
+  const profileById = {};
+  for (const [eachProfileKey, eachProfileValue] of Object.entries(maybeManifest.profiles)) {
+    profileById[eachProfileKey] = validateProfileDefinition(eachProfileKey, eachProfileValue);
+  }
+  assertUniqueProfileIdentities(profileById);
+  /** @type {string[]} */
+  const allMigrationOrderIds = [];
+  for (const eachOrderedProfileId of maybeManifest.migrationOrder) {
+    if (typeof eachOrderedProfileId !== 'string' || !(eachOrderedProfileId in profileById)) {
+      throw new Error(`migrationOrder references unknown profile id: ${String(eachOrderedProfileId)}`);
+    }
+    allMigrationOrderIds.push(eachOrderedProfileId);
+  }
+  return {
+    schemaVersion,
+    profilesRootPlaceholder: requireNonEmptyString(
+      maybeManifest.profilesRootPlaceholder,
+      'profilesRootPlaceholder',
+    ),
+    sharedSourcePlaceholder: requireNonEmptyString(
+      maybeManifest.sharedSourcePlaceholder,
+      'sharedSourcePlaceholder',
+    ),
+    pluginSeedPlaceholder: requireNonEmptyString(
+      maybeManifest.pluginSeedPlaceholder,
+      'pluginSeedPlaceholder',
+    ),
+    migrationOrder: allMigrationOrderIds,
+    profileById,
+  };
+}
+
+/**
+ * @param {unknown} maybeAllowlist
+ * @returns {ValidatedSharedAllowlist}
+ */
+export function validateSharedAllowlist(maybeAllowlist) {
+  if (!isPlainObject(maybeAllowlist)) {
+    throw new Error('shared allowlist must be a JSON object');
+  }
+  if (maybeAllowlist.schemaVersion !== LAUNCHER_SCHEMA_VERSION) {
+    throw new Error(`shared allowlist schemaVersion must be ${LAUNCHER_SCHEMA_VERSION}`);
+  }
+  return {
+    schemaVersion: LAUNCHER_SCHEMA_VERSION,
+    allSharedRelativePaths: requireStringArray(
+      maybeAllowlist.allSharedRelativePaths,
+      'allSharedRelativePaths',
+    ),
+    allAlwaysLocalRelativePaths: requireStringArray(
+      maybeAllowlist.allAlwaysLocalRelativePaths,
+      'allAlwaysLocalRelativePaths',
+    ),
+    allDesktopExcludedPathFragments: requireStringArray(
+      maybeAllowlist.allDesktopExcludedPathFragments,
+      'allDesktopExcludedPathFragments',
+    ),
+  };
+}
+
+/**
+ * @returns {ValidatedProfilesManifest}
+ */
+export function loadAndValidateProfilesManifest() {
+  return validateProfilesManifest(loadProfilesManifestDocument());
+}
+
+/**
+ * @returns {ValidatedSharedAllowlist}
+ */
+export function loadAndValidateSharedAllowlist() {
+  return validateSharedAllowlist(loadSharedAllowlistDocument());
+}
+
+/**
+ * @param {ValidatedProfilesManifest} validatedManifest
+ * @param {string} profileIdOrAlias
+ * @returns {ProfileDefinition}
+ */
+export function resolveProfileDefinition(validatedManifest, profileIdOrAlias) {
+  if (typeof profileIdOrAlias !== 'string') {
+    throw new Error(`Unknown profile id or alias: ${String(profileIdOrAlias)}`);
+  }
+  const normalizedIdentity = profileIdOrAlias.trim().toLowerCase();
+  for (const eachProfile of Object.values(validatedManifest.profileById)) {
+    const allProfileIdentities = [
+      eachProfile.id,
+      ...eachProfile.aliases,
+      ...eachProfile.launcherNames,
+      ...eachProfile.fullLauncherNames,
+    ];
+    if (
+      allProfileIdentities.some(
+        (eachIdentity) => eachIdentity.trim().toLowerCase() === normalizedIdentity,
+      )
+    ) {
+      return eachProfile;
+    }
+  }
+  throw new Error(`Unknown profile id or alias: ${profileIdOrAlias}`);
+}
+
+/**
+ * @param {string} profilesRootDirectoryPath
+ * @param {ProfileDefinition} profileDefinition
+ * @returns {string}
+ */
+export function resolveProfileRootDirectoryPath(profilesRootDirectoryPath, profileDefinition) {
+  return join(profilesRootDirectoryPath, profileDefinition.directoryName);
+}
+
+/**
+ * Reject a launcher name, alias, or id claimed by more than one profile.
+ *
+ * ::
+ *
+ *     profiles['profile-c'].launcherNames = ["claude"]
+ *     profiles.master.launcherNames = ["claude"]
+ *     flag: same identity claimed twice → resolve order would be nondeterministic
+ *     ok:   each identity maps to exactly one profile id
+ *
+ * @param {Record<string, ProfileDefinition>} profileById
+ * @returns {void}
+ */
+function assertUniqueProfileIdentities(profileById) {
+  /** @type {Map<string, string>} */
+  const profileIdByNormalizedIdentity = new Map();
+  for (const eachProfile of Object.values(profileById)) {
+    const allProfileIdentities = [
+      eachProfile.id,
+      ...eachProfile.aliases,
+      ...eachProfile.launcherNames,
+      ...eachProfile.fullLauncherNames,
+    ];
+    for (const eachIdentity of allProfileIdentities) {
+      const normalizedIdentity = eachIdentity.trim().toLowerCase();
+      const previousProfileId = profileIdByNormalizedIdentity.get(normalizedIdentity);
+      if (previousProfileId !== undefined) {
+        throw new Error(
+          `duplicate profile identity '${eachIdentity}' claimed by ${previousProfileId} and ${eachProfile.id}`,
+        );
+      }
+      profileIdByNormalizedIdentity.set(normalizedIdentity, eachProfile.id);
+    }
+  }
+}
+
+/**
+ * @param {string} profileKey
+ * @param {unknown} maybeProfile
+ * @returns {ProfileDefinition}
+ */
+function validateProfileDefinition(profileKey, maybeProfile) {
+  if (!isPlainObject(maybeProfile)) {
+    throw new Error(`profile ${profileKey} must be an object`);
+  }
+  const profileId = requireNonEmptyString(maybeProfile.id, `${profileKey}.id`);
+  if (profileId !== profileKey) {
+    throw new Error(`profile key ${profileKey} must match id ${profileId}`);
+  }
+  const migrationMode = requireNonEmptyString(maybeProfile.migrationMode, `${profileKey}.migrationMode`);
+  if (!ALL_ALLOWED_MIGRATION_MODES.has(migrationMode)) {
+    throw new Error(`profile ${profileKey} has unsupported migrationMode: ${migrationMode}`);
+  }
+  const mcpBundle = requireNonEmptyString(maybeProfile.mcpBundle, `${profileKey}.mcpBundle`);
+  if (!ALL_ALLOWED_MCP_BUNDLES.has(mcpBundle)) {
+    throw new Error(`profile ${profileKey} has unsupported mcpBundle: ${mcpBundle}`);
+  }
+  return {
+    id: profileId,
+    aliases: requireStringArray(maybeProfile.aliases, `${profileKey}.aliases`),
+    directoryName: requireNonEmptyString(maybeProfile.directoryName, `${profileKey}.directoryName`),
+    launcherNames: requireStringArray(maybeProfile.launcherNames, `${profileKey}.launcherNames`),
+    fullLauncherNames: requireStringArray(
+      maybeProfile.fullLauncherNames,
+      `${profileKey}.fullLauncherNames`,
+    ),
+    migrationMode,
+    mcpBundle,
+  };
+}
+
+/**
+ * @param {unknown} candidate
+ * @returns {candidate is Record<string, unknown>}
+ */
+function isPlainObject(candidate) {
+  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate);
+}
+
+/**
+ * @param {unknown} candidate
+ * @param {string} fieldName
+ * @returns {string}
+ */
+function requireNonEmptyString(candidate, fieldName) {
+  if (typeof candidate !== 'string' || candidate.trim() === '') {
+    throw new Error(`${fieldName} must be a non-empty string`);
+  }
+  return candidate;
+}
+
+/**
+ * @param {unknown} candidate
+ * @param {string} fieldName
+ * @returns {string[]}
+ */
+function requireStringArray(candidate, fieldName) {
+  if (
+    !Array.isArray(candidate) ||
+    candidate.some(
+      (eachEntry) => typeof eachEntry !== 'string' || eachEntry.trim() === '',
+    )
+  ) {
+    throw new Error(`${fieldName} must be an array of non-empty strings`);
+  }
+  return /** @type {string[]} */ (candidate);
+}