@git.zone/cli 3.2.1 → 4.0.0

package/ts_migration/002.runtime-config.ts

@@ -0,0 +1,218 @@
+import * as plugins from '../ts/plugins.js';
+import {
+  deriveS3BucketName,
+  isValidS3BucketName,
+} from '../ts/mod_services/classes.serviceconfiguration.js';
+import { withInterProcessLock } from '../ts/mod_services/classes.interprocesslock.js';
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const stringFields = [
+  'PROJECT_NAME',
+  'MONGODB_HOST',
+  'MONGODB_NAME',
+  'MONGODB_PORT',
+  'MONGODB_USER',
+  'MONGODB_PASS',
+  'MONGODB_URL',
+  'S3_HOST',
+  'S3_PORT',
+  'S3_UI_PORT',
+  'S3_CONSOLE_PORT',
+  'S3_ACCESSKEY',
+  'S3_SECRETKEY',
+  'S3_ADMIN_PASSWORD',
+  'S3_REGION',
+  'S3_BUCKET',
+  'S3_ENDPOINT',
+  'ELASTICSEARCH_HOST',
+  'ELASTICSEARCH_PORT',
+  'ELASTICSEARCH_USER',
+  'ELASTICSEARCH_PASS',
+  'ELASTICSEARCH_URL',
+] as const;
+
+const booleanFields = ['MONGODB_AUTH_ENABLED', 'S3_USESSL'] as const;
+const portFields = [
+  'MONGODB_PORT',
+  'S3_PORT',
+  'S3_UI_PORT',
+  'S3_CONSOLE_PORT',
+  'ELASTICSEARCH_PORT',
+] as const;
+
+const assertValidPort = (nameArg: string, valueArg: unknown): void => {
+  if (typeof valueArg !== 'string' || !/^\d{1,5}$/u.test(valueArg)) {
+    throw new Error(`Cannot migrate .nogit/env.json: ${nameArg} must be a decimal port string.`);
+  }
+  const port = Number(valueArg);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new Error(`Cannot migrate .nogit/env.json: ${nameArg} is outside the TCP port range.`);
+  }
+};
+
+/** Validate every known persisted field before a migration is allowed to write. */
+export const assertServiceRuntimeConfigMigrationInput = (
+  configArg: unknown,
+): Record<string, unknown> => {
+  if (!isPlainObject(configArg)) {
+    throw new Error('Cannot migrate .nogit/env.json: root must be a JSON object.');
+  }
+  for (const field of stringFields) {
+    if (
+      Object.hasOwn(configArg, field) &&
+      (typeof configArg[field] !== 'string' || !configArg[field].trim())
+    ) {
+      throw new Error(
+        `Cannot migrate .nogit/env.json: ${field} must be a non-empty string.`,
+      );
+    }
+  }
+  for (const field of booleanFields) {
+    if (Object.hasOwn(configArg, field) && typeof configArg[field] !== 'boolean') {
+      throw new Error(`Cannot migrate .nogit/env.json: ${field} must be a boolean.`);
+    }
+  }
+  for (const field of portFields) {
+    if (Object.hasOwn(configArg, field)) {
+      assertValidPort(field, configArg[field]);
+    }
+  }
+  const s3Port = configArg.S3_PORT;
+  const uiPort = configArg.S3_UI_PORT ?? configArg.S3_CONSOLE_PORT;
+  if (s3Port !== undefined && uiPort !== undefined && s3Port === uiPort) {
+    throw new Error('Cannot migrate .nogit/env.json: S3 API and UI ports must differ.');
+  }
+  return configArg;
+};
+
+export type TLegacyS3BucketRepair =
+  | { bucket: unknown; repaired: false }
+  | { bucket: string; repaired: true };
+
+/** Repair only the exact invalid bucket value generated by older GitZone releases. */
+export const repairLegacyGeneratedS3Bucket = (
+  projectNameArg: string,
+  bucketArg: unknown,
+): TLegacyS3BucketRepair => {
+  const legacyGeneratedBucket = `${projectNameArg}-documents`;
+  if (bucketArg !== legacyGeneratedBucket || isValidS3BucketName(bucketArg)) {
+    return { bucket: bucketArg, repaired: false };
+  }
+  return { bucket: deriveS3BucketName(projectNameArg), repaired: true };
+};
+
+export interface IServiceRuntimeConfigMigrationResult {
+  config: Record<string, unknown>;
+  migrated: boolean;
+}
+
+/** Convert only shipped ObjectStorage predecessor fields and generated values. */
+export const migrateLegacyServiceRuntimeConfigValue = (
+  configArg: unknown,
+): IServiceRuntimeConfigMigrationResult => {
+  const source = assertServiceRuntimeConfigMigrationInput(configArg);
+  const config = { ...source };
+  let migrated = false;
+
+  if (Object.hasOwn(config, 'S3_CONSOLE_PORT')) {
+    const legacyPort = config.S3_CONSOLE_PORT as string;
+    if (Object.hasOwn(config, 'S3_UI_PORT') && config.S3_UI_PORT !== legacyPort) {
+      throw new Error(
+        'Cannot migrate .nogit/env.json: S3_CONSOLE_PORT and S3_UI_PORT contain different values. ' +
+          'Choose the intended management UI port explicitly, keep it as S3_UI_PORT, and remove S3_CONSOLE_PORT.',
+      );
+    }
+    config.S3_UI_PORT = legacyPort;
+    delete config.S3_CONSOLE_PORT;
+    migrated = true;
+  }
+
+  if (!Object.hasOwn(config, 'S3_ADMIN_PASSWORD')) {
+    config.S3_ADMIN_PASSWORD = plugins.crypto.randomBytes(24).toString('base64url');
+    migrated = true;
+  }
+  if (!Object.hasOwn(config, 'S3_REGION')) {
+    config.S3_REGION = 'us-east-1';
+    migrated = true;
+  }
+
+  if (typeof config.PROJECT_NAME === 'string' && typeof config.S3_BUCKET === 'string') {
+    const repair = repairLegacyGeneratedS3Bucket(config.PROJECT_NAME, config.S3_BUCKET);
+    if (repair.repaired) {
+      config.S3_BUCKET = repair.bucket;
+      migrated = true;
+    }
+  }
+
+  assertServiceRuntimeConfigMigrationInput(config);
+  return { config, migrated };
+};
+
+const readRuntimeConfig = async (projectPathArg: string): Promise<unknown | undefined> => {
+  const configPath = plugins.path.join(projectPathArg, '.nogit', 'env.json');
+  if (!(await plugins.smartfs.file(configPath).exists())) {
+    return undefined;
+  }
+  const content = (await plugins.smartfs.file(configPath).encoding('utf8').read()) as string;
+  try {
+    return JSON.parse(content);
+  } catch {
+    throw new Error('Cannot migrate .nogit/env.json: file contains invalid JSON.');
+  }
+};
+
+const writeRuntimeConfigAtomic = async (
+  projectPathArg: string,
+  configArg: Record<string, unknown>,
+): Promise<void> => {
+  const configPath = plugins.path.join(projectPathArg, '.nogit', 'env.json');
+  const tempPath = `${configPath}.tmp-${process.pid}-${plugins.crypto
+    .randomBytes(12)
+    .toString('hex')}`;
+  try {
+    await plugins.fs.writeFile(tempPath, `${JSON.stringify(configArg, null, 2)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600,
+    });
+    await plugins.fs.rename(tempPath, configPath);
+  } catch (error) {
+    await plugins.fs.rm(tempPath, { force: true }).catch(() => {});
+    throw new Error('Cannot migrate .nogit/env.json atomically.', { cause: error });
+  }
+};
+
+export const preflightServiceRuntimeConfigMigration = async (
+  projectPathArg: string,
+): Promise<void> => {
+  const parsed = await readRuntimeConfig(projectPathArg);
+  if (parsed !== undefined) {
+    migrateLegacyServiceRuntimeConfigValue(parsed);
+  }
+};
+
+export const runServiceRuntimeConfigMigration = async (
+  projectPathArg: string,
+): Promise<boolean> => {
+  await preflightServiceRuntimeConfigMigration(projectPathArg);
+  const configPath = plugins.path.join(projectPathArg, '.nogit', 'env.json');
+  return withInterProcessLock(
+    {
+      lockPath: `${configPath}.lock`,
+      description: 'Service runtime configuration',
+    },
+    async () => {
+      const parsed = await readRuntimeConfig(projectPathArg);
+      if (parsed === undefined) {
+        return false;
+      }
+      const migration = migrateLegacyServiceRuntimeConfigValue(parsed);
+      if (migration.migrated) {
+        await writeRuntimeConfigAtomic(projectPathArg, migration.config);
+      }
+      return migration.migrated;
+    },
+  );
+};

package/ts_migration/003.service-data-marker.ts

@@ -0,0 +1,216 @@
+import * as plugins from '../ts/plugins.js';
+import {
+  getLegacyMinioDataDirectory,
+  getServiceDataDirectory,
+  getServiceDataMarkerLockPath,
+  getServiceDataMarkerPath,
+  isValidServiceDataMarker,
+  serviceDataMarkerSchemaVersion,
+  serviceDataOwner,
+  type IServiceDataMarker,
+  type IServiceDataMarkerEntry,
+  type TLegacyServiceName,
+  type TServiceName,
+} from '../ts/mod_services/classes.servicedatamarker.js';
+import { withInterProcessLock } from '../ts/mod_services/classes.interprocesslock.js';
+
+interface IServiceDataMarkerV1 {
+  owner: string;
+  kind: 'service-data';
+  schemaVersion: 1;
+  projectPath: string;
+  safeToPrune: true;
+  createdAt: string;
+  dataDirectories: Array<{
+    service: TServiceName | TLegacyServiceName;
+    path: string;
+  }>;
+}
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const hasOnlyKeys = (
+  valueArg: Record<string, unknown>,
+  allowedKeysArg: readonly string[],
+): boolean =>
+  Object.keys(valueArg).every((keyArg) => allowedKeysArg.includes(keyArg));
+
+const isValidServiceDataMarkerV1 = (markerArg: unknown): markerArg is IServiceDataMarkerV1 => {
+  if (
+    !isPlainObject(markerArg) ||
+    !hasOnlyKeys(markerArg, [
+      'owner',
+      'kind',
+      'schemaVersion',
+      'projectPath',
+      'safeToPrune',
+      'createdAt',
+      'dataDirectories',
+    ]) ||
+    markerArg.owner !== serviceDataOwner ||
+    markerArg.kind !== 'service-data' ||
+    markerArg.schemaVersion !== 1 ||
+    markerArg.safeToPrune !== true ||
+    typeof markerArg.projectPath !== 'string' ||
+    !markerArg.projectPath ||
+    typeof markerArg.createdAt !== 'string' ||
+    !markerArg.createdAt ||
+    !Array.isArray(markerArg.dataDirectories)
+  ) {
+    return false;
+  }
+  const projectPath = plugins.path.resolve(markerArg.projectPath);
+  const seenServices = new Set<string>();
+  for (const entry of markerArg.dataDirectories) {
+    const service = isPlainObject(entry) ? entry.service : undefined;
+    if (
+      !isPlainObject(entry) ||
+      !hasOnlyKeys(entry, ['service', 'path']) ||
+      typeof service !== 'string' ||
+      !['mongodb', 'minio', 'elasticsearch'].includes(service) ||
+      seenServices.has(service) ||
+      typeof entry.path !== 'string'
+    ) {
+      return false;
+    }
+    const expectedPath =
+      service === 'minio'
+        ? getLegacyMinioDataDirectory(projectPath)
+        : getServiceDataDirectory(projectPath, service as TServiceName);
+    if (plugins.path.resolve(entry.path) !== expectedPath) {
+      return false;
+    }
+    seenServices.add(service);
+  }
+  return true;
+};
+
+export interface IServiceDataMarkerMigrationResult {
+  marker?: IServiceDataMarker;
+  migrated: boolean;
+}
+
+/** Convert the exact shipped v1 marker without reinterpreting legacy storage data. */
+export const migrateServiceDataMarkerValue = (
+  markerArg: unknown,
+  projectPathArg: string,
+): IServiceDataMarkerMigrationResult => {
+  const projectPath = plugins.path.resolve(projectPathArg);
+  if (isValidServiceDataMarker(markerArg)) {
+    return {
+      marker:
+        plugins.path.resolve(markerArg.projectPath) === projectPath ? markerArg : undefined,
+      migrated: false,
+    };
+  }
+  if (
+    !isValidServiceDataMarkerV1(markerArg) ||
+    plugins.path.resolve(markerArg.projectPath) !== projectPath
+  ) {
+    return { migrated: false };
+  }
+
+  const dataDirectories: IServiceDataMarkerEntry[] = markerArg.dataDirectories
+    .filter((entry) => entry.service !== 'minio')
+    .map((entry) => ({
+      service: entry.service as TServiceName,
+      path: plugins.path.resolve(entry.path),
+    }))
+    .sort((entryA, entryB) => entryA.service.localeCompare(entryB.service));
+  const legacyEntry = markerArg.dataDirectories.find((entry) => entry.service === 'minio');
+  const marker: IServiceDataMarker = {
+    owner: serviceDataOwner,
+    kind: 'service-data',
+    schemaVersion: serviceDataMarkerSchemaVersion,
+    projectPath,
+    safeToPrune: true,
+    createdAt: markerArg.createdAt,
+    dataDirectories,
+    ...(legacyEntry
+      ? {
+          legacyDataDirectories: [
+            {
+              service: 'minio' as const,
+              path: plugins.path.resolve(legacyEntry.path),
+              safeToPrune: false as const,
+            },
+          ],
+        }
+      : {}),
+  };
+  return { marker, migrated: true };
+};
+
+const readServiceDataMarkerMigrationInput = async (
+  projectPathArg: string,
+): Promise<unknown | undefined> => {
+  const markerPath = getServiceDataMarkerPath(projectPathArg);
+  if (!(await plugins.smartfs.file(markerPath).exists())) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    const content = (await plugins.smartfs.file(markerPath).encoding('utf8').read()) as string;
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`Cannot migrate invalid service data marker: ${markerPath}`);
+  }
+  return parsed;
+};
+
+export const preflightServiceDataMarkerMigration = async (
+  projectPathArg: string,
+): Promise<IServiceDataMarker | undefined> => {
+  const markerPath = getServiceDataMarkerPath(projectPathArg);
+  const parsed = await readServiceDataMarkerMigrationInput(projectPathArg);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  const result = migrateServiceDataMarkerValue(parsed, projectPathArg);
+  if (!result.marker) {
+    throw new Error(`Cannot migrate invalid or foreign service data marker: ${markerPath}`);
+  }
+  return result.marker;
+};
+
+export const runServiceDataMarkerMigration = async (
+  projectPathArg: string,
+): Promise<IServiceDataMarker | undefined> => {
+  await preflightServiceDataMarkerMigration(projectPathArg);
+  const markerPath = getServiceDataMarkerPath(projectPathArg);
+  return withInterProcessLock(
+    {
+      lockPath: getServiceDataMarkerLockPath(projectPathArg),
+      description: 'Service data marker',
+    },
+    async () => {
+      const parsed = await readServiceDataMarkerMigrationInput(projectPathArg);
+      if (parsed === undefined) {
+        return undefined;
+      }
+      const result = migrateServiceDataMarkerValue(parsed, projectPathArg);
+      if (!result.marker) {
+        throw new Error(`Cannot migrate invalid or foreign service data marker: ${markerPath}`);
+      }
+      if (result.migrated) {
+        const tempPath = `${markerPath}.tmp-${process.pid}-${plugins.crypto
+          .randomBytes(12)
+          .toString('hex')}`;
+        try {
+          await plugins.fs.writeFile(tempPath, `${JSON.stringify(result.marker, null, 2)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+          });
+          await plugins.fs.rename(tempPath, markerPath);
+        } catch (error) {
+          await plugins.fs.rm(tempPath, { force: true }).catch(() => {});
+          throw new Error(`Cannot migrate service data marker atomically: ${markerPath}`, {
+            cause: error,
+          });
+        }
+      }
+      return result.marker;
+    },
+  );
+};

package/ts_migration/004.global-registry.ts

@@ -0,0 +1,272 @@
+import * as plugins from '../ts/plugins.js';
+import { migratePersistedServiceNamesValue } from './001.service-selection.js';
+import {
+  GlobalRegistryStore,
+  type IGlobalRegistryTransactionResult,
+  type IGlobalRegistryData,
+  type IRegisteredProject,
+} from '../ts/mod_services/classes.globalregistrystore.js';
+
+export interface IGlobalRegistryMigrationResult {
+  data: IGlobalRegistryData;
+  migrated: boolean;
+}
+
+export interface IGlobalRegistryMigrationStore {
+  readRaw(): Promise<unknown>;
+  transact<T>(
+    operationArg: (
+      rawDataArg: unknown,
+    ) => Promise<IGlobalRegistryTransactionResult<T>> | IGlobalRegistryTransactionResult<T>,
+  ): Promise<T>;
+}
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const assertAllowedKeys = (
+  valueArg: Record<string, unknown>,
+  allowedKeysArg: readonly string[],
+  contextArg: string,
+): void => {
+  if (Object.keys(valueArg).some((keyArg) => !allowedKeysArg.includes(keyArg))) {
+    throw new Error(
+      `Cannot migrate global services registry: ${contextArg} contains unsupported fields.`,
+    );
+  }
+};
+
+const assertOptionalStrings = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  contextArg: string,
+): void => {
+  for (const key of keysArg) {
+    if (valueArg[key] !== undefined && (typeof valueArg[key] !== 'string' || !valueArg[key])) {
+      throw new Error(
+        `Cannot migrate global services registry: ${contextArg}.${key} must be a non-empty string.`,
+      );
+    }
+  }
+};
+
+const assertOptionalNumbers = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  contextArg: string,
+): void => {
+  for (const key of keysArg) {
+    if (valueArg[key] !== undefined && !Number.isFinite(valueArg[key])) {
+      throw new Error(
+        `Cannot migrate global services registry: ${contextArg}.${key} must be a finite number.`,
+      );
+    }
+  }
+};
+
+/** Convert the exact legacy registry fields without activating old provider resources. */
+export const migrateLegacyGlobalRegistryData = (
+  dataArg: unknown,
+): IGlobalRegistryMigrationResult => {
+  if (!isPlainObject(dataArg)) {
+    throw new Error('Cannot migrate global services registry: root must be a JSON object.');
+  }
+  const source = dataArg;
+  assertAllowedKeys(source, ['schemaVersion', 'projects'], 'root');
+  if (source.schemaVersion !== undefined && source.schemaVersion !== 2) {
+    throw new Error('Cannot migrate global services registry: unsupported schema version.');
+  }
+  if (source.projects === undefined) {
+    if (source.schemaVersion === 2) {
+      throw new Error('Cannot migrate global services registry: projects map is missing.');
+    }
+    return {
+      data: { schemaVersion: 2, projects: {} },
+      migrated: true,
+    };
+  }
+  if (!isPlainObject(source.projects)) {
+    throw new Error('Cannot migrate global services registry: projects must be a JSON object.');
+  }
+  let migrated = source.schemaVersion !== 2;
+  const projects: Record<string, IRegisteredProject> = {};
+
+  for (const [projectPath, rawProject] of Object.entries(source.projects)) {
+    if (!isPlainObject(rawProject)) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: project must be a JSON object.`,
+      );
+    }
+    assertAllowedKeys(
+      rawProject,
+      [
+        'projectPath',
+        'projectName',
+        'containers',
+        'ports',
+        'legacy',
+        'enabledServices',
+        'lastActive',
+      ],
+      `project ${projectPath}`,
+    );
+    if (
+      typeof rawProject.projectPath !== 'string' ||
+      !rawProject.projectPath ||
+      plugins.path.resolve(rawProject.projectPath) !== plugins.path.resolve(projectPath)
+    ) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: project path is invalid or inconsistent.`,
+      );
+    }
+    if (typeof rawProject.projectName !== 'string' || !rawProject.projectName) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: project name is invalid.`,
+      );
+    }
+    if (!isPlainObject(rawProject.containers) || !isPlainObject(rawProject.ports)) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: containers and ports must be JSON objects.`,
+      );
+    }
+    if (!Array.isArray(rawProject.enabledServices)) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: enabledServices must be an array.`,
+      );
+    }
+    if (
+      typeof rawProject.lastActive !== 'number' ||
+      !Number.isFinite(rawProject.lastActive)
+    ) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: lastActive must be a finite number.`,
+      );
+    }
+    const rawContainers = rawProject.containers;
+    const rawPorts = rawProject.ports;
+    assertAllowedKeys(
+      rawContainers,
+      ['mongo', 'minio', 'objectstorage', 'elasticsearch'],
+      `project ${projectPath} containers`,
+    );
+    assertOptionalStrings(
+      rawContainers,
+      ['mongo', 'minio', 'objectstorage', 'elasticsearch'],
+      `project ${projectPath}.containers`,
+    );
+    assertAllowedKeys(
+      rawPorts,
+      ['mongo', 's3', 's3Console', 's3Ui', 'elasticsearch'],
+      `project ${projectPath} ports`,
+    );
+    assertOptionalNumbers(
+      rawPorts,
+      ['mongo', 's3', 's3Console', 's3Ui', 'elasticsearch'],
+      `project ${projectPath}.ports`,
+    );
+    let rawLegacy: Record<string, unknown> = {};
+    if (rawProject.legacy !== undefined) {
+      if (!isPlainObject(rawProject.legacy)) {
+        throw new Error(
+          `Cannot migrate global services registry for ${projectPath}: legacy must be a JSON object.`,
+        );
+      }
+      rawLegacy = rawProject.legacy;
+      assertAllowedKeys(rawLegacy, ['minioContainer'], `project ${projectPath} legacy`);
+      assertOptionalStrings(
+        rawLegacy,
+        ['minioContainer'],
+        `project ${projectPath}.legacy`,
+      );
+      if (!rawLegacy.minioContainer) {
+        throw new Error(
+          `Cannot migrate global services registry for ${projectPath}: empty legacy evidence is invalid.`,
+        );
+      }
+    }
+    if (
+      rawLegacy.minioContainer !== undefined &&
+      rawContainers.minio !== undefined &&
+      rawLegacy.minioContainer !== rawContainers.minio
+    ) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: legacy MinIO references differ.`,
+      );
+    }
+    const minioContainer =
+      typeof rawLegacy.minioContainer === 'string'
+        ? rawLegacy.minioContainer
+        : typeof rawContainers.minio === 'string'
+          ? rawContainers.minio
+          : undefined;
+    if (typeof rawContainers.minio === 'string') {
+      migrated = true;
+    }
+    if (
+      rawPorts.s3Ui !== undefined &&
+      rawPorts.s3Console !== undefined &&
+      rawPorts.s3Ui !== rawPorts.s3Console
+    ) {
+      throw new Error(
+        `Cannot migrate global services registry for ${projectPath}: s3Ui and s3Console differ.`,
+      );
+    }
+    if (rawPorts.s3Console !== undefined) {
+      migrated = true;
+    }
+    const s3UiPort = rawPorts.s3Ui ?? rawPorts.s3Console;
+    const serviceMigration = migratePersistedServiceNamesValue(rawProject.enabledServices);
+    migrated ||= serviceMigration.migrated;
+
+    projects[projectPath] = {
+      projectPath: rawProject.projectPath,
+      projectName: rawProject.projectName,
+      containers: {
+        ...(typeof rawContainers.mongo === 'string' ? { mongo: rawContainers.mongo } : {}),
+        ...(typeof rawContainers.objectstorage === 'string'
+          ? { objectstorage: rawContainers.objectstorage }
+          : {}),
+        ...(typeof rawContainers.elasticsearch === 'string'
+          ? { elasticsearch: rawContainers.elasticsearch }
+          : {}),
+      },
+      ports: {
+        ...(typeof rawPorts.mongo === 'number' ? { mongo: rawPorts.mongo } : {}),
+        ...(typeof rawPorts.s3 === 'number' ? { s3: rawPorts.s3 } : {}),
+        ...(typeof s3UiPort === 'number' ? { s3Ui: s3UiPort } : {}),
+        ...(typeof rawPorts.elasticsearch === 'number'
+          ? { elasticsearch: rawPorts.elasticsearch }
+          : {}),
+      },
+      ...(minioContainer ? { legacy: { minioContainer } } : {}),
+      enabledServices: serviceMigration.services,
+      lastActive: rawProject.lastActive,
+    };
+  }
+
+  return {
+    data: { schemaVersion: 2, projects },
+    migrated,
+  };
+};
+
+const createDefaultStore = (): IGlobalRegistryMigrationStore => new GlobalRegistryStore();
+
+export const preflightGlobalRegistryMigration = async (
+  storeArg: IGlobalRegistryMigrationStore = createDefaultStore(),
+): Promise<IGlobalRegistryData> => {
+  return migrateLegacyGlobalRegistryData(await storeArg.readRaw()).data;
+};
+
+export const runGlobalRegistryMigration = async (
+  storeArg: IGlobalRegistryMigrationStore = createDefaultStore(),
+): Promise<IGlobalRegistryData> => {
+  await preflightGlobalRegistryMigration(storeArg);
+  return storeArg.transact((rawData) => {
+    const migration = migrateLegacyGlobalRegistryData(rawData);
+    return {
+      result: migration.data,
+      ...(migration.migrated ? { writeData: migration.data } : {}),
+    };
+  });
+};