import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { pathToFileURL } from 'node:url';

import { MatrixRuntime } from '@open-matrix/core/runtime/MatrixRuntime.js';
import type { MatrixActor } from '@open-matrix/core/core/MatrixActor.js';
import { RequestReply } from '@open-matrix/core/engine/remoting/RequestReply.js';
import { NatsTransport } from '@open-matrix/core/transport/NatsTransport.js';
import { connect as natsConnect, jwtAuthenticator, type NatsConnection } from 'nats';

import { loadMatrixServiceManifest, type ILoadedMatrixServiceManifest } from '../utils/service-manifest.js';
import { createRunnerSecurityRealm } from '../utils/runner-security.js';

export interface IActorRunCommandOptions {
  readonly key?: string;
  readonly cloud?: string;
  readonly space?: string;
  readonly home?: string;
  readonly export?: string;
  readonly mount?: string;
  readonly json?: boolean;
  readonly props?: string;
  readonly ttlSeconds?: number;
  readonly checkOp?: string;
  readonly checkPayload?: string;
}

export interface IActorRunProviderResolution {
  readonly key: string;
  readonly cloud: string;
  readonly space: string;
  readonly checked: readonly string[];
}

interface IActorCredentialExchange {
  readonly ok?: unknown;
  readonly error?: unknown;
  readonly space?: {
    readonly authorityRoot?: unknown;
    readonly spaceId?: unknown;
    readonly routeKey?: unknown;
    readonly publicNamespace?: unknown;
  };
  readonly transport?: {
    readonly natsUrl?: unknown;
    readonly root?: unknown;
  };
  readonly mount?: unknown;
  readonly effectiveMount?: unknown;
  readonly credentials?: {
    readonly jwt?: unknown;
    readonly seed?: unknown;
    readonly userPublicKey?: unknown;
    readonly expiresAt?: unknown;
  };
  readonly source?: unknown;
  readonly credentialPipeline?: unknown;
}

type ActorConstructor = {
  new (): MatrixActor;
  readonly accepts?: Record<string, unknown>;
  readonly emits?: Record<string, unknown>;
  readonly subscribes?: Record<string, unknown>;
  readonly name: string;
};

type PackageBootstrapFunction = (...args: readonly unknown[]) => Promise<unknown> | unknown;

export interface IPackageRunCommandOptions extends IActorRunCommandOptions {
  readonly entry?: string;
  readonly overrides?: string;
}

export interface IPackageRunSpec {
  readonly packageDir: string;
  readonly packageName: string;
  readonly manifestPath: string;
  readonly entryPath: string;
  readonly exportName: string;
  readonly mount: string;
  readonly actorId: string;
  readonly packageId: string;
  readonly runtimeId: string;
  readonly accepts: Record<string, unknown>;
  readonly emits: Record<string, unknown>;
  readonly subscribes: Record<string, unknown>;
  readonly overrides: Record<string, unknown>;
  readonly serviceInstance: ILoadedMatrixServiceManifest['serviceInstance'];
}

export async function actorRunCommand(
  entry: string,
  options: IActorRunCommandOptions,
): Promise<void> {
  const entryPath = path.resolve(entry);
  if (!fs.existsSync(entryPath)) {
    throw new Error(`Actor entry not found: ${entryPath}`);
  }
  const exportName = options.export?.trim() || 'default';
  const ActorClass = await loadActorConstructor(entryPath, exportName);
  const mount = options.mount?.trim() || inferMountFromEntry(entryPath);
  if (!mount) {
    throw new Error('matrix actor run requires --mount <mount> when it cannot infer a mount from the entry file');
  }
  const provider = resolveActorRunProvider(options);
  const exchange = await exchangeActorCredential({
    provider,
    mount,
    actorId: ActorClass.name || mount,
    packageId: readPackageNameForEntry(entryPath) ?? 'standalone-actor',
    runtimeId: `standalone-actor:${process.pid}:${mount}`,
    accepts: ActorClass.accepts ?? {},
    emits: ActorClass.emits ?? {},
    subscribes: ActorClass.subscribes ?? {},
    ttlSeconds: options.ttlSeconds,
  });
  const authorityRoot = readRequiredString(exchange.space?.authorityRoot, 'actor credential response space.authorityRoot');
  const natsUrl = readRequiredString(exchange.transport?.natsUrl, 'actor credential response transport.natsUrl');
  const jwt = readRequiredString(exchange.credentials?.jwt, 'actor credential response credentials.jwt');
  const seed = readRequiredString(exchange.credentials?.seed, 'actor credential response credentials.seed');
  const connection = await connectActorNats({
    natsUrl,
    authorityRoot,
    jwt,
    seed,
  });
  const transport = new NatsTransport(connection, { root: authorityRoot });
  const runtime = new MatrixRuntime({
    transport,
    logging: false,
    allowDynamicCompilation: false,
    securityRealm: createRunnerSecurityRealm(),
  });

  const props = parseProps(options.props);
  await runtime.createSupervised(ActorClass, mount, props);
  await transport.flush();
  const check = await runOptionalActorCheck(runtime, mount, options);

  const result = {
    ok: true,
    mode: 'standalone-actor-runner',
    entry: entryPath,
    export: exportName,
    actor: ActorClass.name,
    mount,
    authorityRoot,
    effectiveMount: resolveEffectiveMount(exchange.effectiveMount, authorityRoot, mount),
    cloud: provider.cloud,
    natsUrl,
    source: readRequiredString(exchange.source, 'actor credential response source'),
    credentialPipeline: readRequiredString(exchange.credentialPipeline, 'actor credential response credentialPipeline'),
    hostStateWritten: false,
    ...(check ? { check } : {}),
  };

  if (options.json) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log('Actor mounted:');
    console.log(`  logical:   ${result.mount}`);
    console.log(`  authority: ${result.authorityRoot}`);
    console.log(`  effective: ${result.effectiveMount}`);
    console.log(`  cloud:     ${result.cloud}`);
    console.log('Press Ctrl+C to stop.');
  }

  if (check) {
    await runtime.shutdown();
    await transport.disconnect();
    if (!connection.isClosed()) {
      await connection.close();
    }
    return;
  }

  await waitForActorShutdown(async () => {
    await runtime.shutdown();
    await transport.disconnect();
    if (!connection.isClosed()) {
      await connection.close();
    }
  });
}

export async function packageRunCommand(
  packageDir: string,
  options: IPackageRunCommandOptions,
): Promise<void> {
  const spec = resolvePackageRunSpec(packageDir, options);
  const provider = resolveActorRunProvider(options);
  const exchange = await exchangeActorCredential({
    provider,
    mount: spec.mount,
    actorId: spec.actorId,
    packageId: spec.packageId,
    runtimeId: spec.runtimeId,
    accepts: spec.accepts,
    emits: spec.emits,
    subscribes: spec.subscribes,
    ttlSeconds: options.ttlSeconds,
  });
  const authorityRoot = readRequiredString(exchange.space?.authorityRoot, 'actor credential response space.authorityRoot');
  const natsUrl = readRequiredString(exchange.transport?.natsUrl, 'actor credential response transport.natsUrl');
  const jwt = readRequiredString(exchange.credentials?.jwt, 'actor credential response credentials.jwt');
  const seed = readRequiredString(exchange.credentials?.seed, 'actor credential response credentials.seed');
  const connection = await connectActorNats({
    natsUrl,
    authorityRoot,
    jwt,
    seed,
  });
  const transport = new NatsTransport(connection, { root: authorityRoot });
  const runtime = new MatrixRuntime({
    transport,
    logging: false,
    allowDynamicCompilation: false,
    securityRealm: createRunnerSecurityRealm(),
  });

  const bootstrap = await loadPackageBootstrap(spec.entryPath, spec.exportName);
  const bootstrapResult = await bootstrap(
    spec.overrides,
    { runtime },
    undefined,
    {
      packageName: spec.packageName,
      packageDir: spec.packageDir,
      manifestPath: spec.manifestPath,
      entryPath: spec.entryPath,
      exportName: spec.exportName,
      root: authorityRoot,
      mount: spec.mount,
      instance: spec.serviceInstance,
      serviceInstance: spec.serviceInstance,
    },
  );
  await transport.flush();
  const check = await runOptionalActorCheck(runtime, spec.mount, options);

  const result = {
    ok: true,
    mode: 'standalone-package-runner',
    packageDir: spec.packageDir,
    packageName: spec.packageName,
    manifest: spec.manifestPath,
    entry: spec.entryPath,
    export: spec.exportName,
    mount: spec.mount,
    authorityRoot,
    effectiveMount: resolveEffectiveMount(exchange.effectiveMount, authorityRoot, spec.mount),
    cloud: provider.cloud,
    natsUrl,
    source: readRequiredString(exchange.source, 'actor credential response source'),
    credentialPipeline: readRequiredString(exchange.credentialPipeline, 'actor credential response credentialPipeline'),
    hostStateWritten: false,
    ...(check ? { check } : {}),
  };

  if (options.json) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log('Package actor mounted:');
    console.log(`  package:   ${result.packageName}`);
    console.log(`  logical:   ${result.mount}`);
    console.log(`  authority: ${result.authorityRoot}`);
    console.log(`  effective: ${result.effectiveMount}`);
    console.log(`  cloud:     ${result.cloud}`);
    console.log('Press Ctrl+C to stop.');
  }

  if (check) {
    await shutdownPackageBootstrapResult(bootstrapResult, runtime);
    await runtime.shutdown();
    await transport.disconnect();
    if (!connection.isClosed()) {
      await connection.close();
    }
    return;
  }

  await waitForActorShutdown(async () => {
    await shutdownPackageBootstrapResult(bootstrapResult, runtime);
    await runtime.shutdown();
    await transport.disconnect();
    if (!connection.isClosed()) {
      await connection.close();
    }
  });
}

export function resolveActorRunProvider(options: IActorRunCommandOptions): IActorRunProviderResolution {
  const home = path.resolve(options.home?.trim() || path.join(os.homedir(), '.matrix'));
  const homeCredential = readApiKeyCredentialFile(path.join(home, 'credentials', 'matrix-api-key.json'));
  const homeConfig = readApiKeyConfigFile(path.join(home, 'config.json'));
  const defaultHome = path.resolve(os.homedir(), '.matrix');
  const defaultCredential = home === defaultHome ? {} : readApiKeyCredentialFile(path.join(defaultHome, 'credentials', 'matrix-api-key.json'));
  const defaultConfig = home === defaultHome ? {} : readApiKeyConfigFile(path.join(defaultHome, 'config.json'));
  const hivecastNamedCredential = readApiKeyCredentialFile(path.join(defaultHome, 'credentials', 'hivecast-api-key.json'));
  const key = readOptionalString(options.key)
    ?? readOptionalString(process.env.MATRIX_API_KEY)
    ?? readOptionalString(process.env.HIVECAST_API_KEY)
    ?? homeCredential.key
    ?? homeConfig.key
    ?? defaultCredential.key
    ?? defaultConfig.key
    ?? hivecastNamedCredential.key;
  const cloud = readOptionalString(options.cloud)
    ?? readOptionalString(process.env.MATRIX_CLOUD)
    ?? readOptionalString(process.env.HIVECAST_CLOUD)
    ?? homeCredential.cloud
    ?? homeConfig.cloud
    ?? defaultCredential.cloud
    ?? defaultConfig.cloud
    ?? hivecastNamedCredential.cloud;
  const space = readOptionalString(options.space)
    ?? readOptionalString(process.env.MATRIX_SPACE)
    ?? readOptionalString(process.env.HIVECAST_SPACE)
    ?? homeCredential.space
    ?? homeConfig.space
    ?? defaultCredential.space
    ?? defaultConfig.space
    ?? hivecastNamedCredential.space;

  const checked = [
    '--key',
    'MATRIX_API_KEY',
    'HIVECAST_API_KEY',
    '<home>/credentials/matrix-api-key.json',
    '<home>/config.json',
    '~/.matrix/credentials/matrix-api-key.json',
    '~/.matrix/config.json',
    '~/.matrix/credentials/hivecast-api-key.json',
  ];

  if (!key) {
    throw new Error(`MATRIX_API_KEY_REQUIRED: matrix actor run requires --key or a configured API key. Checked: ${checked.join(', ')}`);
  }
  if (!cloud) {
    throw new Error('MATRIX_CLOUD_REQUIRED: matrix actor run requires --cloud or configured MATRIX_CLOUD/HIVECAST_CLOUD');
  }
  if (!space) {
    throw new Error('MATRIX_SPACE_REQUIRED: matrix actor run requires --space or configured MATRIX_SPACE/HIVECAST_SPACE');
  }
  return {
    key,
    cloud: normalizeCloudUrl(cloud),
    space,
    checked,
  };
}

export async function exchangeActorCredential(input: {
  readonly provider: IActorRunProviderResolution;
  readonly mount: string;
  readonly actorId: string;
  readonly packageId: string;
  readonly runtimeId: string;
  readonly accepts: Record<string, unknown>;
  readonly emits: Record<string, unknown>;
  readonly subscribes: Record<string, unknown>;
  readonly ttlSeconds?: number;
  readonly fetchImpl?: typeof fetch;
}): Promise<IActorCredentialExchange> {
  const fetchImpl = input.fetchImpl ?? fetch;
  const response = await fetchImpl(new URL('/api/install/actor-credential', input.provider.cloud), {
    method: 'POST',
    headers: {
      authorization: `Bearer ${input.provider.key}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      space: input.provider.space,
      mount: input.mount,
      actorId: input.actorId,
      packageId: input.packageId,
      runtimeId: input.runtimeId,
      accepts: input.accepts,
      emits: input.emits,
      subscribes: input.subscribes,
      ...(input.ttlSeconds ? { ttlSeconds: input.ttlSeconds } : {}),
    }),
  });
  const body = await response.json().catch(() => null) as IActorCredentialExchange | null;
  if (!response.ok || body?.ok !== true) {
    const error = readOptionalString(body?.error) ?? `HTTP_${response.status}`;
    throw new Error(`ACTOR_CREDENTIAL_EXCHANGE_FAILED: ${error}`);
  }
  return body;
}

export function resolvePackageRunSpec(packageDir: string, options: IPackageRunCommandOptions): IPackageRunSpec {
  const loaded = loadMatrixServiceManifest(packageDir);
  const entryPath = options.entry
    ? resolvePackageEntryPath(loaded.packageDir, options.entry)
    : loaded.entryPath;
  const exportName = options.export?.trim() || loaded.exportName;
  const mount = options.mount?.trim() || loaded.mount;
  if (!mount) {
    throw new Error('matrix package run requires --mount <mount> when the package descriptor does not declare one');
  }
  const binding = resolvePackageBindingForMount(loaded, mount);
  const componentType = binding?.type ?? loaded.serviceInstance.componentType ?? loaded.serviceInstance.class;
  const actorId = componentType || mount;
  const runtimeId = `standalone-package:${process.pid}:${sanitizeRuntimeIdPart(loaded.packageName)}:${sanitizeRuntimeIdPart(mount)}`;
  return {
    packageDir: loaded.packageDir,
    packageName: loaded.packageName,
    manifestPath: loaded.manifestPath,
    entryPath,
    exportName,
    mount,
    actorId,
    packageId: loaded.packageName,
    runtimeId,
    accepts: acceptsArrayToRecord(binding?.accepts ?? []),
    emits: {},
    subscribes: {},
    overrides: parseOverrides(options.overrides),
    serviceInstance: loaded.serviceInstance,
  };
}

async function connectActorNats(input: {
  readonly natsUrl: string;
  readonly authorityRoot: string;
  readonly jwt: string;
  readonly seed: string;
}): Promise<NatsConnection> {
  const encoder = new TextEncoder();
  return await natsConnect({
    servers: [input.natsUrl],
    name: `matrix-actor-run-${input.authorityRoot}-${process.pid}`,
    timeout: 5_000,
    authenticator: jwtAuthenticator(
      () => input.jwt,
      () => encoder.encode(input.seed),
    ),
  });
}

export async function loadActorConstructor(entryPath: string, exportName: string): Promise<ActorConstructor> {
  const moduleUrl = `${pathToFileURL(entryPath).href}?matrix_actor_run=${Date.now()}-${Math.random().toString(16).slice(2)}`;
  const mod = await import(moduleUrl) as Record<string, unknown>;
  const requested = actorConstructorFromExport(mod[exportName]);
  if (requested) {
    return requested;
  }
  const available = Object.entries(mod)
    .filter(([, value]) => actorConstructorFromExport(value))
    .map(([name]) => name);
  throw new Error(`No actor class found as export "${exportName}". Available exports: ${available.join(', ') || '(none)'}`);
}

async function loadPackageBootstrap(entryPath: string, exportName: string): Promise<PackageBootstrapFunction> {
  const moduleUrl = `${pathToFileURL(entryPath).href}?matrix_package_run=${Date.now()}-${Math.random().toString(16).slice(2)}`;
  const mod = await import(moduleUrl) as Record<string, unknown>;
  const bootstrap = mod[exportName];
  if (typeof bootstrap !== 'function') {
    throw new Error(`Package run export "${exportName}" was not found in ${entryPath}`);
  }
  return bootstrap as PackageBootstrapFunction;
}

function actorConstructorFromExport(value: unknown): ActorConstructor | null {
  if (typeof value !== 'function') {
    return null;
  }
  const candidate = value as ActorConstructor;
  return candidate.prototype ? candidate : null;
}

function inferMountFromEntry(entryPath: string): string {
  return path.basename(entryPath, path.extname(entryPath))
    .replace(/Actor$/i, '')
    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
    .toLowerCase()
    .replace(/[^a-z0-9._-]+/g, '-')
    .replace(/-+/g, '-')
    .replace(/^-|-$/g, '');
}

function readPackageNameForEntry(entryPath: string): string | undefined {
  let dir = path.dirname(entryPath);
  while (dir !== path.dirname(dir)) {
    const packageJsonPath = path.join(dir, 'package.json');
    if (fs.existsSync(packageJsonPath)) {
      const parsed = readJsonFile(packageJsonPath);
      return readOptionalString(parsed?.name);
    }
    dir = path.dirname(dir);
  }
  return undefined;
}

function parseProps(value: string | undefined): Record<string, unknown> | undefined {
  const text = value?.trim();
  if (!text) {
    return undefined;
  }
  const parsed = JSON.parse(text) as unknown;
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new Error('matrix actor run --props must be a JSON object');
  }
  return parsed as Record<string, unknown>;
}

function parseOverrides(value: string | undefined): Record<string, unknown> {
  const text = value?.trim();
  if (!text) {
    return {};
  }
  const parsed = JSON.parse(text) as unknown;
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new Error('matrix package run --overrides must be a JSON object');
  }
  return parsed as Record<string, unknown>;
}

async function runOptionalActorCheck(
  runtime: MatrixRuntime,
  mount: string,
  options: IActorRunCommandOptions,
): Promise<{ readonly op: string; readonly result: unknown } | null> {
  const op = options.checkOp?.trim();
  if (!op) {
    return null;
  }
  const payload = parseCheckPayload(options.checkPayload);
  const result = await RequestReply.execute<Record<string, unknown>, unknown>(
    runtime.getRootContext(),
    mount,
    op,
    payload,
    { timeoutMs: 5_000 },
  );
  return { op, result };
}

function parseCheckPayload(value: string | undefined): Record<string, unknown> {
  const text = value?.trim();
  if (!text) {
    return {};
  }
  const parsed = JSON.parse(text) as unknown;
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new Error('matrix actor/package run --check-payload must be a JSON object');
  }
  return parsed as Record<string, unknown>;
}

function resolvePackageEntryPath(packageDir: string, entry: string): string {
  const trimmed = entry.trim();
  if (!trimmed) {
    throw new Error('matrix package run --entry must be a non-empty path');
  }
  const entryPath = path.resolve(packageDir, trimmed);
  if (!fs.existsSync(entryPath)) {
    throw new Error(`matrix package run entry does not exist: ${trimmed}`);
  }
  return entryPath;
}

function resolvePackageBindingForMount(
  loaded: ILoadedMatrixServiceManifest,
  mount: string,
): ILoadedMatrixServiceManifest['packageComponents'][number] | ILoadedMatrixServiceManifest['packageRoot'] | undefined {
  if (loaded.packageRoot?.mount === mount) {
    return loaded.packageRoot;
  }
  return loaded.packageComponents.find((entry) => entry.mount === mount);
}

function acceptsArrayToRecord(accepts: readonly string[]): Record<string, unknown> {
  const result: Record<string, unknown> = {};
  for (const op of accepts) {
    result[op] = {};
  }
  return result;
}

function sanitizeRuntimeIdPart(value: string): string {
  return value
    .replace(/^@/u, '')
    .replace(/[^a-zA-Z0-9._-]+/gu, '-')
    .replace(/-+/gu, '-')
    .replace(/^-|-$/gu, '')
    || 'package';
}

async function shutdownPackageBootstrapResult(value: unknown, ownedRuntime: MatrixRuntime): Promise<void> {
  if (!value || typeof value !== 'object') {
    return;
  }
  const runtime = (value as { readonly runtime?: unknown }).runtime;
  if (!runtime || typeof runtime !== 'object') {
    return;
  }
  if (runtime === ownedRuntime) {
    return;
  }
  const shutdown = (runtime as { readonly shutdown?: unknown }).shutdown;
  if (typeof shutdown === 'function') {
    await shutdown.call(runtime);
  }
}

function waitForActorShutdown(onShutdown: () => Promise<void>): Promise<void> {
  return new Promise<void>((resolve, reject) => {
    let settled = false;
    const finish = (error?: unknown): void => {
      if (settled) return;
      settled = true;
      process.off('SIGINT', shutdown);
      process.off('SIGTERM', shutdown);
      if (error) {
        reject(error);
        return;
      }
      resolve();
    };
    const shutdown = (): void => {
      void onShutdown().then(() => finish()).catch((error) => finish(error));
    };
    process.on('SIGINT', shutdown);
    process.on('SIGTERM', shutdown);
  });
}

function readApiKeyCredentialFile(filePath: string): { readonly key?: string; readonly cloud?: string; readonly space?: string } {
  const value = readJsonFile(filePath);
  return {
    ...(readOptionalString(value?.apiKey) ?? readOptionalString(value?.key) ? { key: (readOptionalString(value?.apiKey) ?? readOptionalString(value?.key))! } : {}),
    ...(readOptionalString(value?.cloud) ? { cloud: readOptionalString(value?.cloud)! } : {}),
    ...(readOptionalString(value?.space) ?? readOptionalString(value?.authorityRoot) ? { space: (readOptionalString(value?.space) ?? readOptionalString(value?.authorityRoot))! } : {}),
  };
}

function readApiKeyConfigFile(filePath: string): { readonly key?: string; readonly cloud?: string; readonly space?: string } {
  const value = readJsonFile(filePath);
  const apiKey = value?.apiKey && typeof value.apiKey === 'object' && !Array.isArray(value.apiKey)
    ? value.apiKey as Record<string, unknown>
    : {};
  return {
    ...(readOptionalString(apiKey.apiKey) ?? readOptionalString(apiKey.key) ? { key: (readOptionalString(apiKey.apiKey) ?? readOptionalString(apiKey.key))! } : {}),
    ...(readOptionalString(value?.cloud) ?? readOptionalString(value?.hivecastCloud) ? { cloud: (readOptionalString(value?.cloud) ?? readOptionalString(value?.hivecastCloud))! } : {}),
    ...(readOptionalString(value?.space) ?? readOptionalString(value?.authorityRoot) ? { space: (readOptionalString(value?.space) ?? readOptionalString(value?.authorityRoot))! } : {}),
  };
}

function readJsonFile(filePath: string): Record<string, unknown> | null {
  if (!fs.existsSync(filePath)) {
    return null;
  }
  try {
    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    throw new Error(`Invalid JSON in ${filePath}: ${message}`);
  }
}

function readRequiredString(value: unknown, label: string): string {
  const result = readOptionalString(value);
  if (!result) {
    throw new Error(`Missing ${label}`);
  }
  return result;
}

function readOptionalString(value: unknown): string | undefined {
  if (typeof value !== 'string') {
    return undefined;
  }
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : undefined;
}

function resolveEffectiveMount(value: unknown, authorityRoot: string, mount: string): string {
  const fromExchange = readOptionalString(value);
  if (fromExchange) {
    return fromExchange;
  }
  return `${authorityRoot}.${mount}`;
}

function normalizeCloudUrl(value: string): string {
  const parsed = new URL(value);
  return parsed.toString().replace(/\/$/, '');
}