@docupace/pipeline 1.0.137 → 1.1.1

package/src/next/connect-aws.js

@@ -0,0 +1,1858 @@
+import fs from 'fs-extra';
+import axios from 'axios';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { parseArgs, promisify, isDeepStrictEqual } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+import {
+  CreateSecretCommand,
+  SecretsManagerClient,
+} from '@aws-sdk/client-secrets-manager';
+import { runPipeline } from './pipline.js';
+import { environmentConfig, getBitbucketInfo } from './config.js';
+
+// Loaded lazily so deploy.js can import this module without pulling in the Auth0 and AWS secret helpers.
+const loadSecretsManager = () => import('../auth0/secrets-manager.js');
+const loadAwsSecrets = () => import('../aws/aws-secrets.js');
+
+// Existing AWS CONNECT deployment
+export const CONNECT_AWS_GITOPS_REPO = 'dp-eks-connect-ui-gitops';
+export const CONNECT_AWS_UPDATE_PIPELINE = 'update-site-image';
+export const CONNECT_AWS_DEFAULT_BRANCH = 'main';
+
+const ALLOWED_ENVS = new Set(['dev', 'qa', 'stage', 'uat', 'prod']);
+const SITE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+
+/**
+ * Normalize sites input to a non-empty list of site names.
+ * Accepts a single site string, comma-separated string, or string[].
+ *
+ * @param {string|string[]} sites
+ * @returns {string[]}
+ */
+export function normalizeConnectAwsSites(sites) {
+  const raw = Array.isArray(sites) ? sites : String(sites ?? '').split(',');
+  return raw.map((s) => String(s).trim()).filter(Boolean);
+}
+
+/**
+ * Trigger the Bitbucket custom pipeline that updates
+ * envs/<env>/<site>/values.yaml image.tag in dp-eks-connect-ui-gitops.
+ *
+ * @param {string} env - Target environment (dev|qa|stage|uat|prod)
+ * @param {string|string[]} sites - Site name, or comma-separated / array of sites
+ * @param {string} version - Image tag to deploy
+ * @param {{ wait?: boolean, branch?: string }} [options]
+ */
+export async function deployConnectAws(
+  env,
+  sites,
+  version,
+  { wait = true, branch = CONNECT_AWS_DEFAULT_BRANCH } = {},
+) {
+  const siteList = normalizeConnectAwsSites(sites);
+  validateConnectAwsArgs(env, siteList, version);
+
+  const siteParam = siteList.join(',');
+  console.log(
+    `Deploying AWS Connect UI: env=${env} site(s)=${siteParam} version=${version} (pipeline=${CONNECT_AWS_UPDATE_PIPELINE})`,
+  );
+
+  await runPipeline(
+    CONNECT_AWS_GITOPS_REPO,
+    CONNECT_AWS_UPDATE_PIPELINE,
+    branch,
+    {
+      ENV: env,
+      SITE: siteParam,
+      VERSION: version,
+    },
+    wait,
+  );
+}
+
+/**
+ * @param {string} env
+ * @param {string|string[]} sites - single site, comma-separated, or array
+ * @param {string} version
+ */
+export function validateConnectAwsArgs(env, sites, version) {
+  if (!ALLOWED_ENVS.has(env)) {
+    throw new Error(
+      `Invalid env "${env}". Expected one of: ${[...ALLOWED_ENVS].join(', ')}`,
+    );
+  }
+
+  const siteList = normalizeConnectAwsSites(sites);
+  if (siteList.length === 0) {
+    throw new Error('At least one site is required');
+  }
+  for (const site of siteList) {
+    if (!SITE_PATTERN.test(site)) {
+      throw new Error(`Invalid site "${site}"`);
+    }
+  }
+
+  if (!version || !VERSION_PATTERN.test(version)) {
+    throw new Error(`Invalid version "${version}"`);
+  }
+}
+
+export function isAllowedConnectAwsEnv(env) {
+  return ALLOWED_ENVS.has(env);
+}
+
+// Environment normalization
+const aliases = {
+  preprod: 'qa',
+  staging: 'stage',
+  stg: 'stage',
+  prd: 'prod',
+  'prod-www3': 'prod',
+  'prod-las': 'prod',
+  'prod-lax': 'prod',
+  'prod-athene': 'prod',
+  'prod-staging': 'prod',
+};
+
+export function normalizeConnectEnvironment(env) {
+  const normalized = aliases[env] || env;
+  if (!['dev', 'qa', 'stage', 'uat', 'prod'].includes(normalized)) {
+    throw new Error(
+      'CONNECT environment must be dev, qa, stage, uat, or prod.',
+    );
+  }
+  return normalized;
+}
+
+export function getConnectEnvironmentConfig(env) {
+  env = normalizeConnectEnvironment(env);
+  const siteSettingsEnv = { qa: 'preprod', stage: 'staging' }[env] || env;
+  return { env, siteSettingsEnv };
+}
+
+// The pipeline wrappers use the same aliases as the copy, secrets, SAML and fleet commands.
+
+// Target Core settings
+// Read Java properties without executing repository content or logging values.
+export function parseCoreProperties(content) {
+  const result = {};
+  const lines = content.replace(/\\\r?\n[ \t]*/g, '').split(/\r?\n/);
+  for (const line of lines) {
+    if (/^\s*[#!]/.test(line) || !line.trim()) continue;
+    const match = line.match(/^\s*([^\s=:]+)\s*(?:[=:]\s*|\s+)(.*)$/);
+    if (!match) continue;
+    result[match[1]] = match[2]
+      .trim()
+      .replace(/\\u([\da-f]{4})|\\([trnf\\:= ])/gi, (_, hex, escaped) =>
+        hex
+          ? String.fromCharCode(parseInt(hex, 16))
+          : ({ t: '\t', r: '\r', n: '\n', f: '\f' }[escaped] ?? escaped),
+      );
+  }
+  return result;
+}
+
+async function readProperties(file, required = false) {
+  if (!(await fs.pathExists(file))) {
+    if (required)
+      throw new Error(
+        `Target Core site settings are missing: ${path.basename(file)}. Complete Core site setup first.`,
+      );
+    return {};
+  }
+  return parseCoreProperties(await fs.readFile(file, 'utf8'));
+}
+
+export async function readConnectSsoSettings({
+  siteSettingsPath,
+  site,
+  coreSchema,
+}) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,49}$/.test(site || ''))
+    throw new Error('Invalid target site.');
+  const root = await fs.realpath(path.resolve(siteSettingsPath));
+  const schema = coreSchema || site.toUpperCase();
+  if (!/^[A-Z0-9][A-Z0-9_-]{0,49}$/i.test(schema))
+    throw new Error('Invalid target Core schema.');
+  const folder = path.join(root, schema);
+  if (!(await fs.realpath(folder)).startsWith(`${root}${path.sep}`))
+    throw new Error('Target settings resolve outside their checkout.');
+  const sso = await readProperties(
+    path.join(folder, 'docucore-sharedKeySSO.properties'),
+    true,
+  );
+  const matches = Object.entries(sso).filter(
+    ([key, value]) =>
+      /^com\.docupace\.dpflow\.web\.security\.token\.CommonSSOConfig\.tokenRealms\d+\.publicId$/.test(
+        key,
+      ) && /^(Connect|NEWUI)$/i.test(value),
+  );
+  if (matches.length !== 1)
+    throw new Error(
+      'Target site settings require exactly one Connect/NEWUI realm.',
+    );
+  const prefix = matches[0][0].replace(/publicId$/, '');
+  return {
+    key: resolved(sso[`${prefix}key`], 'CONNECT SSO key'),
+    iv: resolved(sso[`${prefix}iv`], 'CONNECT SSO IV'),
+  };
+}
+
+function resolved(value, label) {
+  if (!value || /\$\{|[\r\n]/.test(value)) {
+    throw new Error(
+      `Cannot resolve ${label} from target Core site settings. Complete Core setup or supply an explicit override.`,
+    );
+  }
+  return value;
+}
+
+export async function resolveConnectSiteSettings({
+  siteSettingsPath,
+  env,
+  site,
+  coreSchema,
+  coreRealm,
+  dbUrl,
+  coreApiUrl,
+}) {
+  env = normalizeConnectEnvironment(env);
+  if (!/^[a-z0-9][a-z0-9_-]{0,49}$/.test(site || ''))
+    throw new Error('Invalid target site name.');
+  const root = await fs.realpath(path.resolve(siteSettingsPath));
+  // The existing Core convention uses the uppercase site directory/client name.
+  const schema = coreSchema || site.toUpperCase();
+  if (!/^[A-Z0-9][A-Z0-9_-]{0,49}$/i.test(schema))
+    throw new Error('Invalid target Core schema.');
+  const siteDir = path.join(root, schema);
+  if (
+    !(await fs.pathExists(siteDir)) ||
+    !(await fs.realpath(siteDir)).startsWith(`${root}${path.sep}`)
+  ) {
+    throw new Error(
+      `Target Core site directory ${schema} is missing from site settings. Complete Core site setup first.`,
+    );
+  }
+  let corePublicRealm;
+  if (!coreRealm) {
+    const sso = await readProperties(
+      path.join(siteDir, 'docucore-sharedKeySSO.properties'),
+      true,
+    );
+    const realms = Object.entries(sso).filter(
+      ([key, value]) =>
+        /^com\.docupace\.dpflow\.web\.security\.token\.CommonSSOConfig\.tokenRealms\d+\.publicId$/.test(
+          key,
+        ) && /^(Connect|NEWUI)$/i.test(value),
+    );
+    if (realms.length !== 1)
+      throw new Error(
+        'Target Core site settings require exactly one Connect or NEWUI SSO realm.',
+      );
+    coreRealm = resolved(
+      sso[realms[0][0].replace(/publicId$/, 'privateId')],
+      'CONNECT private realm',
+    );
+    corePublicRealm = realms[0][1];
+  }
+  if (!dbUrl) {
+    const database = {
+      ...(await readProperties(path.join(root, 'docucore.properties'))),
+      ...(await readProperties(path.join(root, 'docucore-jndi.properties'))),
+      ...(await readProperties(path.join(siteDir, 'docucore.properties'))),
+      ...(await readProperties(path.join(siteDir, 'docucore-jndi.properties'))),
+    };
+    const type = resolved(database['docupace.db.type'], 'Core database type');
+    if (type !== 'oracle')
+      throw new Error(
+        'Automatic CONNECT database resolution currently requires Oracle; supply an explicit JDBC override for this site.',
+      );
+    dbUrl = resolved(
+      database[`docupace.db.${type}.dataSourceURL`],
+      'Core JDBC URL',
+    );
+  }
+  return {
+    coreSchema: schema,
+    coreRealm,
+    corePublicRealm,
+    dbUrl,
+    coreApiUrl:
+      coreApiUrl || `https://${environmentConfig[env].docupaceHost()}/core_b2b`,
+  };
+}
+
+// Pod Identity and runtime readiness
+const exec = promisify(execFile);
+export const CONNECT_AWS_ACCOUNTS = {
+  dev: '772533039138',
+  qa: '431655581418',
+  stage: '352311918908',
+  uat: '497172038832',
+  prod: '520326035622',
+};
+
+export async function readConnectAwsJson(args, region) {
+  try {
+    const { stdout } = await exec(
+      'aws',
+      [...args, '--region', region, '--output', 'json', '--no-cli-pager'],
+      { timeout: 30000, maxBuffer: 2 * 1024 * 1024 },
+    );
+    return JSON.parse(stdout);
+  } catch (error) {
+    if (/ResourceNotFoundException/.test(error.stderr || '')) return null;
+    // Never include captured secret responses or credential-bearing arguments.
+    throw new Error(
+      `AWS ${args[0]} ${args[1]} lookup failed; readiness cannot be confirmed.`,
+    );
+  }
+}
+
+function usable(value) {
+  return (
+    typeof value === 'string' &&
+    value.trim() &&
+    !/^(?:null|undefined|changeme|placeholder)$/i.test(value.trim()) &&
+    !value.includes('${') &&
+    !value.trim().startsWith('vault:')
+  );
+}
+
+function configHasValue(config, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = config.match(
+    new RegExp(`^[ \\t]*${escaped}[ \\t]*=[ \\t]*(.+)$`, 'm'),
+  );
+  if (!match) return false;
+  let value = match[1].trim();
+  if (value.startsWith('"')) {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return false;
+    }
+  }
+  return usable(value);
+}
+
+export async function checkConnectReadiness({
+  env,
+  site,
+  region = process.env.AWS_REGION || 'us-west-2',
+  aws = readConnectAwsJson,
+  podIdentityOnly = false,
+}) {
+  env = normalizeConnectEnvironment(env);
+  if (!/^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$/.test(site || ''))
+    throw new Error('Invalid target site name.');
+  const identity = await aws(['sts', 'get-caller-identity'], region);
+  if (identity?.Account !== CONNECT_AWS_ACCOUNTS[env])
+    throw new Error(
+      'AWS account does not match the target CONNECT environment.',
+    );
+  const name = site.replaceAll('_', '-');
+  const cluster = `docupace-${env}-eks`;
+  const namespace = `dp-${name}`;
+  const serviceAccount = `${name}-connect`;
+  const shortRegion = region.replace(
+    /^([a-z]+)-([a-z])[a-z]*-(\d+)$/,
+    '$1$2$3',
+  );
+  const expectedRole = `arn:aws:iam::${identity.Account}:role/${cluster}-connect-ui-pod-identity-${shortRegion}`;
+  const listed = await aws(
+    [
+      'eks',
+      'list-pod-identity-associations',
+      '--cluster-name',
+      cluster,
+      '--namespace',
+      namespace,
+      '--service-account',
+      serviceAccount,
+    ],
+    region,
+  );
+  const reasons = [];
+  if (listed?.associations?.length !== 1) {
+    return {
+      ready: false,
+      reasons: [
+        `Expected one Pod Identity association for ${cluster}/${namespace}/${serviceAccount}.`,
+      ],
+      env,
+      site,
+    };
+  }
+  const described = await aws(
+    [
+      'eks',
+      'describe-pod-identity-association',
+      '--cluster-name',
+      cluster,
+      '--association-id',
+      listed.associations[0].associationId,
+    ],
+    region,
+  );
+  const association = described?.association;
+  if (
+    association?.clusterName !== cluster ||
+    association?.namespace !== namespace ||
+    association?.serviceAccount !== serviceAccount ||
+    association?.roleArn !== expectedRole
+  ) {
+    return {
+      ready: false,
+      reasons: [
+        'Pod Identity association does not match the expected target identity and role.',
+      ],
+      env,
+      site,
+    };
+  }
+  if (podIdentityOnly)
+    return {
+      ready: true,
+      reasons: [],
+      env,
+      site,
+      cluster,
+      namespace,
+      serviceAccount,
+      expectedRole,
+    };
+  const required = [
+    [
+      `docupace/eks/dp-connect-${name}/${name}-secret`,
+      ['db.default.user', 'db.default.password', 'sso.key', 'sso.iv'],
+    ],
+    [
+      `docupace/eks/connect-ui/${env}/common`,
+      [
+        'application.secret',
+        'application.internalEncryption.key',
+        'application.generateTokenKey',
+        'saml.keystorePassword',
+        'saml.privateKeyPassword',
+        'saml.connect.keystorePassword',
+      ],
+    ],
+    ['docupace/eks/artifactory-ms', ['registryHost', 'username', 'password']],
+    [
+      `docupace/eks/dp-${site}/${site}`,
+      ['COMMON_AUTH0_CLIENT_ID', 'COMMON_AUTH0_CLIENT_SECRET'],
+    ],
+  ];
+  for (const [secretName, keys] of required) {
+    const response = await aws(
+      ['secretsmanager', 'get-secret-value', '--secret-id', secretName],
+      region,
+    );
+    if (!response?.SecretString) {
+      reasons.push(`Required secret is missing: ${secretName}.`);
+      continue;
+    }
+    let secret;
+    try {
+      secret = JSON.parse(response.SecretString);
+    } catch {
+      reasons.push(`Required secret is not a JSON object: ${secretName}.`);
+      continue;
+    }
+    if (!secret || typeof secret !== 'object' || Array.isArray(secret)) {
+      reasons.push(`Required secret is not a JSON object: ${secretName}.`);
+      continue;
+    }
+    for (const key of keys) {
+      const present = key.includes('.')
+        ? typeof secret['secret.conf'] === 'string' &&
+          configHasValue(secret['secret.conf'], key)
+        : usable(secret[key]);
+      if (!present)
+        reasons.push(
+          `Required field ${key} is missing or unresolved in ${secretName}.`,
+        );
+    }
+  }
+  return {
+    ready: reasons.length === 0,
+    reasons,
+    env,
+    site,
+    cluster,
+    namespace,
+    serviceAccount,
+    expectedRole,
+  };
+}
+
+// Dedicated CONNECT runtime secret
+const keys = ['db.default.user', 'db.default.password', 'sso.key', 'sso.iv'];
+export function populated(value) {
+  return (
+    typeof value === 'string' &&
+    !!value.trim() &&
+    !/^(null|undefined|changeme|placeholder)$/i.test(value.trim()) &&
+    !value.includes('${') &&
+    !value.trim().startsWith('vault:')
+  );
+}
+export function readRuntimeConfig(content = '') {
+  const values = {};
+  for (const key of keys) {
+    const escaped = key.replaceAll('.', '\\.');
+    const matches = [
+      ...content.matchAll(
+        new RegExp(`^[ \\t]*${escaped}[ \\t]*=[ \\t]*(.+)$`, 'gm'),
+      ),
+    ];
+    if (matches.length > 1)
+      throw new Error(`Duplicate runtime setting: ${key}.`);
+    let value = matches[0]?.[1]?.trim();
+    if (value?.startsWith('"')) {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        value = '';
+      }
+    }
+    if (populated(value)) values[key] = value;
+  }
+  return values;
+}
+async function optionalSecret(name) {
+  const response = await readConnectAwsJson(
+    ['secretsmanager', 'get-secret-value', '--secret-id', name],
+    process.env.AWS_REGION || 'us-west-2',
+  );
+  if (!response) return null;
+  let secret;
+  try {
+    secret = JSON.parse(response.SecretString);
+  } catch {
+    throw new Error(`Secret ${name} must contain a JSON object.`);
+  }
+  if (!secret || typeof secret !== 'object' || Array.isArray(secret))
+    throw new Error(`Secret ${name} must contain a JSON object.`);
+  return secret;
+}
+
+// Keep the dedicated CONNECT secret contract used by existing deployments.
+// Complete secrets are reused; only missing runtime values are populated.
+export async function ensureConnectRuntimeSecret({
+  env,
+  site,
+  coreSchema,
+  siteSettingsPath,
+  dbSourceSecret,
+  dbUserProperty = 'CONNECT_DB_USER',
+  dbPasswordProperty = 'CONNECT_DB_PASSWORD',
+  dryRun = false,
+}) {
+  env = normalizeConnectEnvironment(env);
+  if (!/^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$/.test(site || ''))
+    throw new Error('Invalid target site name.');
+  const identity = await readConnectAwsJson(
+    ['sts', 'get-caller-identity'],
+    process.env.AWS_REGION || 'us-west-2',
+  );
+  if (identity?.Account !== CONNECT_AWS_ACCOUNTS[env])
+    throw new Error(
+      'AWS account does not match the target environment; no secret was written.',
+    );
+  if (dbSourceSecret?.startsWith('arn:'))
+    throw new Error(
+      'Use a target-account secret name for the DB credential source.',
+    );
+  if (dbPasswordProperty === 'CORE_PASSWORD')
+    throw new Error(
+      'CORE_PASSWORD is a Core API credential, not a database password.',
+    );
+  const normalized = site.replaceAll('_', '-');
+  const runtimeName = `docupace/eks/dp-connect-${normalized}/${normalized}-secret`;
+  const sharedName = `docupace/eks/dp-${site}/${site}`;
+  const siteSecret = await optionalSecret(sharedName);
+  if (
+    !siteSecret ||
+    !populated(siteSecret.COMMON_AUTH0_CLIENT_ID) ||
+    !populated(siteSecret.COMMON_AUTH0_CLIENT_SECRET)
+  )
+    throw new Error(
+      'Create the target site secret and management credentials with Step 1 before CONNECT onboarding.',
+    );
+  const runtimeSecret = await optionalSecret(runtimeName);
+  const property = 'secret.conf';
+  const targetName = runtimeName;
+  const existing = runtimeSecret || {};
+  const content = existing[property];
+  if (content !== undefined && typeof content !== 'string')
+    throw new Error('CONNECT runtime configuration must be a string.');
+  const fields = readRuntimeConfig(content);
+  if (keys.every((key) => populated(fields[key])))
+    return {
+      secretName: targetName,
+      secretProperty: null,
+      status: 'existing',
+    };
+  if (!fields['sso.key'] || !fields['sso.iv']) {
+    const sso = await readConnectSsoSettings({
+      siteSettingsPath,
+      site,
+      coreSchema,
+    });
+    if (
+      (fields['sso.key'] && fields['sso.key'] !== sso.key) ||
+      (fields['sso.iv'] && fields['sso.iv'] !== sso.iv)
+    )
+      throw new Error(
+        'Existing partial SSO credentials differ from target Core settings; review the target runtime secret.',
+      );
+    fields['sso.key'] ||= sso.key;
+    fields['sso.iv'] ||= sso.iv;
+  }
+  if (!fields['db.default.user'] || !fields['db.default.password']) {
+    const common =
+      (await optionalSecret(
+        (await loadSecretsManager()).getAwsSharedSecretName(),
+      )) || {};
+    const siteHasDb =
+      populated(siteSecret.CONNECT_DB_USER) ||
+      populated(siteSecret.CONNECT_DB_PASSWORD);
+    const configured = siteHasDb ? siteSecret : common;
+    // DB credentials must be a pair from one target-account source. Never use
+    // CORE_PASSWORD (Core API login) or another environment's source-site secret.
+    if (
+      !dbSourceSecret &&
+      (populated(configured.CONNECT_DB_USER) ||
+        populated(configured.CONNECT_DB_PASSWORD))
+    ) {
+      if (
+        !populated(configured.CONNECT_DB_USER) ||
+        !populated(configured.CONNECT_DB_PASSWORD)
+      )
+        throw new Error(
+          'CONNECT_DB_USER and CONNECT_DB_PASSWORD must be populated together in one target-account secret.',
+        );
+      if (
+        fields['db.default.user'] &&
+        fields['db.default.user'] !== configured.CONNECT_DB_USER
+      )
+        throw new Error(
+          'Existing DB username differs from the shared credential source.',
+        );
+      if (
+        fields['db.default.password'] &&
+        fields['db.default.password'] !== configured.CONNECT_DB_PASSWORD
+      )
+        throw new Error(
+          'Existing DB password differs from the shared credential source.',
+        );
+      fields['db.default.user'] ||= configured.CONNECT_DB_USER;
+      fields['db.default.password'] ||= configured.CONNECT_DB_PASSWORD;
+    } else {
+      let sourceName =
+        dbSourceSecret || 'docupace/eks/dp-connect-template/template-secret';
+      let source = await optionalSecret(sourceName);
+      if (!source && !dbSourceSecret) {
+        sourceName = 'docupace/eks/dp-template/template';
+        source = await optionalSecret(sourceName);
+      }
+      if (!source)
+        throw new Error(
+          `Target DB credential source is missing: ${sourceName}. Configure CONNECT_DB_SOURCE_SECRET or shared CONNECT_DB_USER/CONNECT_DB_PASSWORD.`,
+        );
+      const sourceContent = source['secret.conf'];
+      const sourceFields =
+        typeof sourceContent === 'string'
+          ? readRuntimeConfig(sourceContent)
+          : {};
+      const useProperties =
+        populated(source[dbUserProperty]) ||
+        populated(source[dbPasswordProperty]);
+      const user = useProperties
+        ? source[dbUserProperty]
+        : sourceFields['db.default.user'];
+      const password = useProperties
+        ? source[dbPasswordProperty]
+        : sourceFields['db.default.password'];
+      if (!populated(user) || !populated(password))
+        throw new Error(
+          `Target DB credential source ${sourceName} requires a nonempty username/password pair.`,
+        );
+      if (fields['db.default.user'] && fields['db.default.user'] !== user)
+        throw new Error(
+          'Existing DB username differs from the credential source; refusing to combine credentials from different accounts.',
+        );
+      if (
+        fields['db.default.password'] &&
+        fields['db.default.password'] !== password
+      )
+        throw new Error(
+          'Existing DB password differs from the credential source; refusing to combine credentials from different accounts.',
+        );
+      fields['db.default.user'] = user;
+      fields['db.default.password'] = password;
+    }
+  }
+  for (const key of keys)
+    if (!populated(fields[key]))
+      throw new Error(
+        `CONNECT runtime setting ${key} is empty or unresolved; no secret was written.`,
+      );
+  let updated = content || '';
+  for (const key of keys) {
+    const pattern = new RegExp(
+      `^[ \\t]*${key.replaceAll('.', '\\.')}[ \\t]*=.*$`,
+      'gm',
+    );
+    const line = `${key}=${JSON.stringify(fields[key])}`;
+    updated = pattern.test(updated)
+      ? updated.replace(pattern, () => line)
+      : `${updated.trimEnd()}\n${line}\n`;
+  }
+  if (!dryRun) {
+    // Re-read before writing; preserve other properties and reject concurrent changes.
+    const latest = await optionalSecret(targetName);
+    if (
+      !!latest !== !!runtimeSecret ||
+      latest?.[property] !== existing[property]
+    )
+      throw new Error(
+        'CONNECT runtime secret changed concurrently; retry onboarding.',
+      );
+    if (latest) {
+      await (
+        await loadAwsSecrets()
+      ).saveSecretToAws(targetName, { ...latest, [property]: updated });
+    } else {
+      // Create only the dedicated runtime object, without the shared-site schema.
+      const client = new SecretsManagerClient({
+        region: process.env.AWS_REGION || 'us-west-2',
+      });
+      try {
+        await client.send(
+          new CreateSecretCommand({
+            Name: targetName,
+            SecretString: JSON.stringify({ [property]: updated }),
+            Description: `CONNECT runtime configuration for ${env}/${site}`,
+          }),
+        );
+      } catch (error) {
+        if (error.name === 'ResourceExistsException')
+          throw new Error(
+            'CONNECT runtime secret was created concurrently; retry onboarding.',
+          );
+        throw new Error(
+          'CONNECT runtime secret creation failed; check target AWS permissions and secret state.',
+        );
+      }
+    }
+  }
+  return {
+    secretName: targetName,
+    secretProperty: null,
+    status: dryRun ? 'planned' : 'prepared',
+  };
+}
+
+// Exact source image validation
+export async function checkConnectImage({
+  valuesPath,
+  aws = readConnectAwsJson,
+  request = fetch,
+}) {
+  const config = yaml.load(await fs.readFile(valuesPath, 'utf8'));
+  const app = config?.['dp-connect-ui'];
+  const host = config?.global?.systemRegistry || 'registry.paperout.com';
+  if (
+    !/^[a-z0-9.-]+(?::\d+)?$/i.test(host) ||
+    !/^[a-z0-9][a-z0-9/_.-]*$/.test(app?.image?.repository || '') ||
+    !/^[\w][\w.-]{0,127}$/.test(app?.image?.tag || '')
+  )
+    throw new Error('Generated image reference is invalid.');
+  const result = await aws(
+    [
+      'secretsmanager',
+      'get-secret-value',
+      '--secret-id',
+      'docupace/eks/artifactory-ms',
+    ],
+    process.env.AWS_REGION || 'us-west-2',
+  );
+  const credentials = JSON.parse(result?.SecretString || '{}');
+  if (
+    credentials.registryHost !== host ||
+    !credentials.username ||
+    !credentials.password
+  )
+    throw new Error(
+      'Registry credentials do not match the generated image registry.',
+    );
+  const headers = {
+    Authorization: `Basic ${Buffer.from(`${credentials.username}:${credentials.password}`).toString('base64')}`,
+    Accept:
+      'application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.index.v1+json, application/vnd.oci.image.manifest.v1+json',
+  };
+  const tag = String(app.image.tag);
+  const response = await request(
+    `https://${host}/v2/${app.image.repository}/manifests/${tag}`,
+    {
+      method: 'HEAD',
+      headers,
+      redirect: 'manual',
+      signal: AbortSignal.timeout(30000),
+    },
+  );
+  if (response.status === 404)
+    throw new Error(
+      `CONNECT image ${host}/${app.image.repository}:${tag} is not published; refusing to merge. Select a published source image or explicitly override IMAGE_TAG in the inherited repository.`,
+    );
+  if (!response.ok)
+    throw new Error(
+      `Image registry check failed with HTTP ${response.status}; refusing to merge.`,
+    );
+  console.log(
+    `Published CONNECT image confirmed: ${host}/${app.image.repository}:${tag}`,
+  );
+  return tag;
+}
+
+// CONNECT AWS Auth0 metadata and configuration
+// Match active HOCON assignments by their exact dotted key, preserving comments.
+export function setConfigValues(config, values) {
+  let result = config;
+  for (const [key, value] of Object.entries(values)) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`^[ \\t]*${escaped}[ \\t]*=.*$`, 'gm');
+    const assignment = `${key}=${value}`;
+    result = pattern.test(result)
+      ? result.replace(pattern, () => assignment)
+      : `${result.trimEnd()}\n${assignment}\n`;
+  }
+  return result;
+}
+
+function readConfigString(config, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = config.match(
+    new RegExp(
+      `^[ \\t]*${escaped}[ \\t]*=[ \\t]*(?:"([^"\\r\\n]+)"|([^ \\t\\r\\n#]+))`,
+      'm',
+    ),
+  );
+  const value = match?.[1] || match?.[2];
+  if (!value) throw new Error(`${key} not found in application.conf.`);
+  return value;
+}
+
+export function getConnectEndpoint(config) {
+  const context = readConfigString(config, 'application.context');
+  const hostConfig = /^[ \t]*application\.hostUrl[ \t]*=/m.test(config)
+    ? 'application.hostUrl'
+    : 'docupace.baseUrlClient';
+  const baseUrl = new URL(readConfigString(config, hostConfig));
+  if (baseUrl.protocol !== 'https:' || !context.startsWith('/')) {
+    throw new Error(
+      'CONNECT requires an HTTPS base URL and an absolute context path.',
+    );
+  }
+  return `${baseUrl.origin}${context}`;
+}
+
+// Generates settings without cloning, changing cwd, writing files or pushing.
+// Both site setup and the metadata CLI use this operation.
+export async function prepareAuth0Config({
+  site,
+  env,
+  auth0Tenant = '',
+  appConf,
+  connectEndpoint,
+}) {
+  const { getAuth0AuthToken } = await import('../auth0/configure.js');
+  const normalizedEnv = normalizeConnectEnvironment(env);
+  const tenant =
+    auth0Tenant || `docupace-${normalizedEnv}-${site.replaceAll('_', '-')}`;
+  const auth0Domain = tenant.endsWith('.auth0.com')
+    ? tenant
+    : `${tenant}.us.auth0.com`;
+  if (!/^[a-z0-9-]+(?:\.[a-z0-9-]+)?\.auth0\.com$/i.test(auth0Domain)) {
+    throw new Error(
+      'Auth0 tenant must be a tenant name or an auth0.com domain.',
+    );
+  }
+  const endpoint = connectEndpoint || getConnectEndpoint(appConf);
+  const secrets = await (await loadSecretsManager()).getSiteSecrets(site);
+  const clientId = secrets?.COMMON_AUTH0_CLIENT_ID;
+  const clientSecret = secrets?.COMMON_AUTH0_CLIENT_SECRET;
+  if (
+    typeof clientId !== 'string' ||
+    !clientId.trim() ||
+    typeof clientSecret !== 'string' ||
+    !clientSecret.trim()
+  ) {
+    throw new Error(
+      'Target site requires COMMON_AUTH0_CLIENT_ID and COMMON_AUTH0_CLIENT_SECRET.',
+    );
+  }
+  const token = await getAuth0AuthToken(auth0Domain, clientId, clientSecret);
+  if (!token) throw new Error('Auth0 did not return an access token.');
+  const clients = [];
+  for (let page = 0; ; page += 1) {
+    const response = await axios.get(`https://${auth0Domain}/api/v2/clients`, {
+      headers: { authorization: `Bearer ${token}` },
+      params: {
+        page,
+        per_page: 100,
+        fields: 'name,client_id',
+        include_fields: true,
+      },
+      timeout: 30000,
+    });
+    if (!Array.isArray(response.data))
+      throw new Error('Invalid Auth0 clients response.');
+    clients.push(
+      ...response.data.filter((client) => client.name === 'docupace-connect'),
+    );
+    if (response.data.length < 100) break;
+    if (page >= 99) throw new Error('Auth0 client listing exceeded 100 pages.');
+  }
+  if (
+    clients.length !== 1 ||
+    typeof clients[0].client_id !== 'string' ||
+    !/^[\w-]+$/.test(clients[0].client_id)
+  ) {
+    throw new Error(
+      'Expected exactly one Auth0 client named "docupace-connect".',
+    );
+  }
+  const connectClientId = clients[0].client_id;
+  const { data: metadata } = await axios.get(
+    `https://${auth0Domain}/samlp/metadata/${connectClientId}`,
+    { responseType: 'text', timeout: 30000 },
+  );
+  const matchingSso =
+    typeof metadata === 'string' &&
+    [
+      ...metadata.matchAll(
+        /<(?:[\w-]+:)?SingleSignOnService\b[^>]*\bLocation\s*=\s*["']([^"']+)["']/g,
+      ),
+    ].some(([, location]) => {
+      try {
+        const url = new URL(location);
+        return (
+          url.origin === `https://${auth0Domain}` &&
+          url.pathname === `/samlp/${connectClientId}`
+        );
+      } catch {
+        return false;
+      }
+    });
+  if (
+    typeof metadata !== 'string' ||
+    !/<(?:[\w-]+:)?EntityDescriptor\b/.test(metadata) ||
+    !/<(?:[\w-]+:)?IDPSSODescriptor\b/.test(metadata) ||
+    !matchingSso
+  )
+    throw new Error(
+      'Downloaded SAML metadata does not identify the target Auth0 client.',
+    );
+
+  const logout = new URL(`https://${auth0Domain}/v2/logout`);
+  logout.searchParams.set('client_id', connectClientId);
+  logout.searchParams.set('returnTo', endpoint);
+  const config = setConfigValues(appConf, {
+    useSAML: 'true',
+    'saml.defaultClient': '"auth0"',
+    'saml.clients.auth0.idpMetadataPath': '${samlEnvPath}"/auth0.xml"',
+    'saml.clients.auth0.spEntityId': JSON.stringify(endpoint),
+    'saml.clients.auth0.redirectFormInput': '"RelayState"',
+    'saml.clients.auth0.idpLoginUrl': JSON.stringify(logout.toString()),
+  });
+  return { appConf: config, metadata, endpoint, auth0Domain };
+}
+
+// Site copy and target configuration
+const sitePattern = /^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$/;
+const secretAssignment =
+  /^[ \t]*(?:db\.default\.(?:user|password)|sso\.(?:key|iv)|saml\.(?:connect\.)?(?:keystorePassword|privateKeyPassword)|application\.(?:secret|internalEncryption\.key|generateTokenKey))[ \t]*[:=]/m;
+
+function jdbcHasCredentials(value) {
+  return /(?:[?;](?:user(?:name)?|password|pwd)\s*=|jdbc:oracle:thin:(?!@)[^@\s]+@|:\/\/[^/@\s]+:[^/@\s]+@)/i.test(
+    value,
+  );
+}
+
+function httpsUrl(value, label, originOnly = false) {
+  const url = new URL(value);
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    (originOnly && url.pathname !== '/')
+  ) {
+    throw new Error(
+      `${label} must be an HTTPS ${originOnly ? 'origin' : 'URL'} without credentials, query, or fragment.`,
+    );
+  }
+  return url;
+}
+
+async function assertPlainTree(root) {
+  for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+    const file = path.join(root, entry.name);
+    if (entry.isSymbolicLink())
+      throw new Error(`Template contains a symbolic link: ${entry.name}`);
+    if (entry.isDirectory()) await assertPlainTree(file);
+  }
+}
+
+// Works in an existing checkout. Git push, review branches and AWS authentication
+// belong to the calling pipeline. Replacement requires explicit forceOverwrite.
+export async function copyConnectSite({
+  repoPath = process.cwd(),
+  env,
+  templateSite = 'template',
+  templateEnv,
+  siteSettingsPath,
+  site,
+  coreSchema,
+  coreRealm,
+  dbUrl,
+  coreApiUrl,
+  imageTag,
+  baseUrl,
+  coreUrl,
+  contextPath = '/connect',
+  auth0Tenant = '',
+  forceOverwrite = false,
+  runtimeSecretName,
+}) {
+  env = normalizeConnectEnvironment(env);
+  templateEnv = normalizeConnectEnvironment(templateEnv || env);
+  let corePublicRealm;
+  if (siteSettingsPath) {
+    ({ coreSchema, coreRealm, corePublicRealm, dbUrl, coreApiUrl } =
+      await resolveConnectSiteSettings({
+        siteSettingsPath,
+        env,
+        site,
+        coreSchema,
+        coreRealm,
+        dbUrl,
+        coreApiUrl,
+      }));
+  }
+  if (templateEnv !== env && (!dbUrl?.trim() || !coreApiUrl?.trim())) {
+    throw new Error(
+      'Cross-environment copies require the target DB URL and Core backend URL.',
+    );
+  }
+  if (
+    dbUrl &&
+    (!dbUrl.startsWith('jdbc:') ||
+      /[\r\n]/.test(dbUrl) ||
+      jdbcHasCredentials(dbUrl))
+  ) {
+    throw new Error(
+      'DB URL must be a JDBC URL without inline credentials or newlines.',
+    );
+  }
+  if (!sitePattern.test(site || '') || !sitePattern.test(templateSite)) {
+    throw new Error(
+      'Site and template names must use lowercase letters, numbers, underscores or hyphens (maximum 50 characters).',
+    );
+  }
+  const dedicatedSecretName = `docupace/eks/dp-connect-${site.replaceAll('_', '-')}/${site.replaceAll('_', '-')}-secret`;
+  if (runtimeSecretName && runtimeSecretName !== dedicatedSecretName)
+    throw new Error(
+      'Runtime secret must use the dedicated target CONNECT secret.',
+    );
+  if (
+    !coreSchema?.trim() ||
+    !coreRealm?.trim() ||
+    /[\r\n]/.test(coreSchema + coreRealm)
+  ) {
+    throw new Error('Target Core schema and private realm are required.');
+  }
+  if (!/^\/[a-zA-Z0-9_/-]*$/.test(contextPath) || contextPath.includes('//')) {
+    throw new Error('CONNECT context must be an absolute URL path.');
+  }
+  if (imageTag && !/^[a-zA-Z0-9_][a-zA-Z0-9_.-]{0,127}$/.test(imageTag)) {
+    throw new Error('Image tag must be a valid Docker tag.');
+  }
+  const origin = httpsUrl(
+    baseUrl || environmentConfig[env].newUrl(site.replaceAll('_', '-')),
+    'CONNECT base URL',
+    true,
+  );
+  const core = httpsUrl(coreUrl || `${origin.origin}/core`, 'Core URL');
+  const backend = coreApiUrl ? httpsUrl(coreApiUrl, 'Core backend URL') : null;
+  const repo = await fs.realpath(path.resolve(repoPath));
+  const envDir = path.join(repo, 'envs', env);
+  const source = path.join(repo, 'envs', templateEnv, templateSite);
+  const target = path.join(envDir, site);
+  if (!(await fs.pathExists(source)))
+    throw new Error(
+      `Source site not found: envs/${templateEnv}/${templateSite}`,
+    );
+  if (!(await fs.pathExists(envDir)))
+    throw new Error(`Target environment is not configured: ${env}`);
+  const realEnvDir = await fs.realpath(envDir);
+  if (
+    !realEnvDir.startsWith(`${repo}${path.sep}`) ||
+    (await fs.lstat(envDir)).isSymbolicLink()
+  ) {
+    throw new Error(
+      'Target environment must be a directory inside the GitOps checkout.',
+    );
+  }
+  const realSource = await fs.realpath(source);
+  if (!realSource.startsWith(`${repo}${path.sep}`))
+    throw new Error('Template resolves outside the GitOps checkout.');
+  const k8sName = site.replaceAll('_', '-');
+  const siblings = await fs.readdir(envDir);
+  if (
+    siblings.some(
+      (name) => name !== site && name.replaceAll('_', '-') === k8sName,
+    )
+  ) {
+    throw new Error(`Target site or Kubernetes name already exists: ${site}`);
+  }
+  const existingTarget = siblings.includes(site);
+  if (existingTarget && !forceOverwrite) {
+    throw new Error(
+      `Target site already exists: ${site}. Use --force-overwrite to replace it.`,
+    );
+  }
+  if (existingTarget) {
+    const targetStat = await fs.lstat(target);
+    if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
+      throw new Error(
+        'Existing target must be a plain directory inside the target environment.',
+      );
+    }
+  }
+  await assertPlainTree(source);
+  const sourceConfig = await fs.readFile(
+    path.join(source, 'conf', 'application.conf'),
+    'utf8',
+  );
+  const sourceJdbc = sourceConfig.match(
+    /^[ \t]*db\.default\.url[ \t]*[:=][ \t]*"([^"\r\n]+)"/m,
+  )?.[1];
+  if (
+    secretAssignment.test(sourceConfig) ||
+    (sourceJdbc && jdbcHasCredentials(sourceJdbc))
+  ) {
+    throw new Error(
+      'Template contains inline credentials. Migrate them to Secrets Manager before copying.',
+    );
+  }
+  const values = yaml.load(
+    await fs.readFile(path.join(source, 'values.yaml'), 'utf8'),
+  );
+  const app = values?.['dp-connect-ui'];
+  if (
+    !app?.image?.repository ||
+    !app?.image?.tag ||
+    !app?.initContainer?.s3Bucket
+  ) {
+    throw new Error(
+      'Template values require dp-connect-ui.image.repository, image.tag and initContainer.s3Bucket.',
+    );
+  }
+  if (
+    app.initContainer.s3Bucket !==
+    `docupace-${templateEnv}-connect-ui-configs-usw2`
+  ) {
+    throw new Error('Source S3 bucket does not match the source environment.');
+  }
+  const config = setConfigValues(sourceConfig, {
+    'application.context': JSON.stringify(contextPath),
+    'application.hostUrl': JSON.stringify(origin.origin),
+    'application.baseUrl': JSON.stringify(origin.origin),
+    'application.hostName': JSON.stringify(origin.hostname),
+    'application.cors.allowedOrigins.common': JSON.stringify([origin.origin]),
+    'docupace.baseUrlClient': JSON.stringify(
+      core.toString().replace(/\/$/, ''),
+    ),
+    'docupace.baseUrlSSO': JSON.stringify(core.toString().replace(/\/$/, '')),
+    'docupace.context': JSON.stringify(core.pathname),
+    'docupace.core.context': JSON.stringify(core.pathname),
+    'docupace.db.schemaName': JSON.stringify(coreSchema.trim()),
+    'sso.privateRealm': JSON.stringify(coreRealm.trim()),
+    'saml.connect.enableAutoLogin': 'true',
+    'application.integrations.launchNextUI': 'true',
+    ...(corePublicRealm
+      ? { 'sso.publicRealm': JSON.stringify(corePublicRealm) }
+      : {}),
+    ...(dbUrl ? { 'db.default.url': JSON.stringify(dbUrl.trim()) } : {}),
+    ...(backend
+      ? {
+          'docupace.baseUrl': JSON.stringify(
+            backend.toString().replace(/\/$/, ''),
+          ),
+        }
+      : {}),
+  });
+  // Finish remote reads before creating the target directory.
+  const prepared = await prepareAuth0Config({
+    site,
+    env,
+    auth0Tenant,
+    appConf: config,
+    connectEndpoint: `${origin.origin}${contextPath}`,
+  });
+  app.name = k8sName;
+  app.namespace = `dp-${k8sName}`;
+  app.siteName = site;
+  app.clientName = coreSchema.trim();
+  app.envName = env;
+  // Inherit the selected source image; shared-image migration is a separate action.
+  if (imageTag) app.image.tag = imageTag;
+  app.gateway = { ...app.gateway, hostnames: [origin.hostname], contextPath };
+  app.serviceAccount = {
+    ...app.serviceAccount,
+    create: true,
+    name: `${k8sName}-connect`,
+    imagePullSecrets: ['artifactory-connect'],
+  };
+  if (app.serviceAccount.annotations)
+    delete app.serviceAccount.annotations['eks.amazonaws.com/role-arn'];
+  app.secretName = `${k8sName}-secret`;
+  app.externalSecret = {
+    ...app.externalSecret,
+    enabled: true,
+    clusterSecretStoreName: 'aws-secrets-manager',
+    awsSecretKey:
+      runtimeSecretName ||
+      `docupace/eks/dp-connect-${k8sName}/${k8sName}-secret`,
+  };
+  delete app.externalSecret.awsSecretProperty;
+  app.commonExternalSecret = {
+    ...app.commonExternalSecret,
+    enabled: true,
+    targetSecretName: 'connect-ui-common-secret',
+    awsSecretKey: `docupace/eks/connect-ui/${env}/common`,
+  };
+  app.artifactorySecret = {
+    ...app.artifactorySecret,
+    enabled: true,
+    targetSecretName: 'artifactory-connect',
+    awsSecretKey: 'docupace/eks/artifactory-ms',
+  };
+  app.initContainer.s3Bucket = `docupace-${env}-connect-ui-configs-usw2`;
+  app.initContainer.s3Prefix = 'main';
+  delete app.configVersion;
+  delete app.fullnameOverride;
+  delete app.imagePullSecrets;
+  // Build beside the target so validation/copy failures leave the old site intact.
+  const workDir = await fs.mkdtemp(path.join(realEnvDir, '.connect-copy-'));
+  const generated = path.join(workDir, 'generated');
+  const backup = path.join(workDir, 'previous');
+  let backedUp = false;
+  let installed = false;
+  try {
+    await fs.mkdir(generated);
+    for (const dir of ['conf', 'stylesheets']) {
+      if (await fs.pathExists(path.join(source, dir))) {
+        await fs.copy(path.join(source, dir), path.join(generated, dir), {
+          overwrite: false,
+          errorOnExist: true,
+        });
+      }
+    }
+    await fs.outputFile(
+      path.join(generated, 'conf', 'application.conf'),
+      prepared.appConf,
+    );
+    await fs.outputFile(
+      path.join(generated, 'conf', 'saml', 'auth0.xml'),
+      prepared.metadata,
+    );
+    await fs.writeFile(
+      path.join(generated, 'values.yaml'),
+      yaml.dump(values, { lineWidth: -1 }),
+    );
+    if (existingTarget) {
+      await fs.rename(target, backup);
+      backedUp = true;
+    }
+    await fs.rename(generated, target);
+    installed = true;
+  } catch (error) {
+    if (backedUp && !installed) {
+      try {
+        await fs.rename(backup, target);
+        backedUp = false;
+      } catch {
+        // Preserve the backup if the filesystem prevents restoration.
+        throw new Error(
+          `Replacement failed; the previous site is preserved at ${backup}.`,
+          { cause: error },
+        );
+      }
+    }
+    throw error;
+  } finally {
+    // This absolute directory was created by this run, directly inside realEnvDir.
+    if ((!backedUp || installed) && path.dirname(workDir) === realEnvDir) {
+      await fs.remove(workDir);
+    }
+  }
+  console.log(
+    `${existingTarget ? 'Replaced' : 'Created'} envs/${env}/${site} from ${templateEnv}/${templateSite}; CONNECT endpoint: ${prepared.endpoint}`,
+  );
+  return {
+    siteDir: target,
+    relativeSiteDir: `envs/${env}/${site}`,
+    env,
+    site,
+    namespace: app.namespace,
+    serviceAccount: app.serviceAccount.name,
+    endpoint: prepared.endpoint,
+    sourceEnv: templateEnv,
+    sourceSite: templateSite,
+  };
+}
+
+// Fleet registration and guarded CONNECT fleet publication
+async function insideFile(rootPath, relative) {
+  const root = await fs.realpath(path.resolve(rootPath));
+  const file = await fs.realpath(path.join(root, relative));
+  if (!file.startsWith(`${root}${path.sep}`))
+    throw new Error(`File resolves outside its checkout: ${relative}`);
+  return file;
+}
+
+export async function getFleetValuesSource({ env, nextRepoPath }) {
+  env = normalizeConnectEnvironment(env);
+  const relative = `apps-fleet/values/us-west-2/docupace-${env}-eks/values.yaml`;
+  const fleet = yaml.load(
+    await fs.readFile(await insideFile(nextRepoPath, relative), 'utf8'),
+  );
+  const defaults =
+    yaml.load(
+      await fs.readFile(
+        await insideFile(nextRepoPath, 'apps-fleet/values.yaml'),
+        'utf8',
+      ),
+    ) || {};
+  const repo = fleet.gitopsRepo || defaults.gitopsRepo;
+  const revision = fleet.gitopsRevision || defaults.gitopsRevision;
+  if (repo !== `git@bitbucket.org:dp-cloud/gitops-${env}.git` || !revision)
+    throw new Error(
+      'Fleet must declare the target environment values repository and revision.',
+    );
+  return { repo, revision };
+}
+
+export async function validateConnectFleetChange({
+  env,
+  site,
+  beforeFile,
+  afterFile,
+}) {
+  env = normalizeConnectEnvironment(env);
+  if (!/^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$/.test(site || ''))
+    throw new Error('Invalid target site name.');
+  const projectName = `dp-${env}-eks-connect-ui-project`;
+  const appName = `dp-${site.replaceAll('_', '-')}`;
+  const documents = await Promise.all(
+    [beforeFile, afterFile].map(async (file) =>
+      yaml.load(await fs.readFile(file, 'utf8')),
+    ),
+  );
+  const entries = documents.map((document) => {
+    const projects =
+      document?.projects?.filter((project) => project.name === projectName) ||
+      [];
+    if (projects.length !== 1 || !Array.isArray(projects[0].applications))
+      throw new Error(
+        'Cannot validate CONNECT fleet changes: target project is missing.',
+      );
+    const apps = projects[0].applications.filter((app) => app.name === appName);
+    if (apps.length > 1)
+      throw new Error('Duplicate target CONNECT fleet application.');
+    projects[0].applications = projects[0].applications.filter(
+      (app) => app.name !== appName,
+    );
+    return apps;
+  });
+  if (
+    !isDeepStrictEqual(documents[0], documents[1]) ||
+    (entries[0].length && !isDeepStrictEqual(entries[0], entries[1]))
+  )
+    throw new Error(
+      'Branch changes existing or unrelated fleet configuration; refusing automatic merge.',
+    );
+  if (entries[1].length !== 1)
+    throw new Error('Target CONNECT fleet application is missing.');
+  const entry = entries[1][0];
+  if (
+    entry.enabled === false ||
+    !isDeepStrictEqual(entry.valueFiles, [`../envs/${env}/${site}/values.yaml`])
+  )
+    throw new Error(
+      'Target CONNECT fleet application has an unexpected values path or is disabled.',
+    );
+  return { env, site, valid: true };
+}
+
+// Append entries only within the selected project, retaining existing formatting,
+// comments, pinned revisions and unrelated applications.
+function appendApplications(text, projectName, entries) {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((line) => {
+    const match = line.match(/^(\s*)-\s+name:\s*(.*?)\s*$/);
+    return match && match[2].replace(/^["']|["']$/g, '') === projectName;
+  });
+  if (start < 0) throw new Error(`Fleet project is missing: ${projectName}`);
+  const indent = lines[start].match(/^\s*/)[0].length;
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end];
+    if (
+      line.trim() &&
+      !line.trim().startsWith('#') &&
+      line.match(/^\s*/)[0].length <= indent
+    )
+      break;
+    end += 1;
+  }
+  const appsLine = lines.findIndex(
+    (line, i) =>
+      i > start && i < end && /^\s*applications:\s*(?:\[\])?\s*$/.test(line),
+  );
+  if (appsLine < 0)
+    throw new Error('Fleet applications must use an existing block sequence.');
+  lines[appsLine] = lines[appsLine].replace(/:\s*\[\]\s*$/, ':');
+  const sample = lines
+    .slice(appsLine + 1, end)
+    .find((line) => /^\s*-\s+name:/.test(line));
+  const appIndent = sample ? sample.match(/^\s*/)[0].length : indent + 4;
+  const added = yaml
+    .dump(entries, { lineWidth: -1, noRefs: true })
+    .trimEnd()
+    .split('\n')
+    .map((line) => ' '.repeat(appIndent) + line);
+  lines.splice(end, 0, ...added);
+  return lines.join('\n');
+}
+
+export async function registerSiteApps({
+  env,
+  site,
+  apps = 'CONNECT',
+  connectRepoPath,
+  nextRepoPath,
+  configRepoPath,
+  configRevision,
+  chartRevision = 'develop',
+  dryRun = false,
+}) {
+  env = normalizeConnectEnvironment(env);
+  if (!/^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$/.test(site || ''))
+    throw new Error('Invalid target site name.');
+  const requested = [
+    ...new Set(
+      apps
+        .toUpperCase()
+        .split(',')
+        .map((value) => value.trim()),
+    ),
+  ];
+  if (
+    !requested.length ||
+    requested.some((value) => !['CONNECT', 'CORE', 'NEXT'].includes(value))
+  )
+    throw new Error('APPS must contain CONNECT, CORE and/or NEXT.');
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_./-]*$/.test(chartRevision || ''))
+    throw new Error('A valid CORE/NEXT chart revision is required.');
+  const name = site.replaceAll('_', '-');
+  const relative = `apps-fleet/values/us-west-2/docupace-${env}-eks/values.yaml`;
+  const plans = [];
+  for (const kind of ['CONNECT', 'NEXT']) {
+    const selected =
+      kind === 'CONNECT'
+        ? requested.includes('CONNECT')
+        : requested.some((value) => value !== 'CONNECT');
+    if (!selected) continue;
+    const repo = kind === 'CONNECT' ? connectRepoPath : nextRepoPath;
+    if (!repo) throw new Error(`${kind} GitOps checkout is required.`);
+    const file = await insideFile(repo, relative);
+    const text = await fs.readFile(file, 'utf8');
+    const fleet = yaml.load(text);
+    if (fleet.env !== env || fleet.name !== `docupace-${env}-eks`)
+      throw new Error('Fleet environment/cluster does not match the target.');
+    const projectName = `dp-${env}-eks-${kind === 'CONNECT' ? 'connect-ui' : 'next'}-project`;
+    const projects =
+      fleet.projects?.filter((project) => project.name === projectName) || [];
+    if (projects.length !== 1 || !Array.isArray(projects[0].applications))
+      throw new Error(
+        `Expected exactly one configured project ${projectName}.`,
+      );
+    const candidates = [];
+    if (kind === 'CONNECT') {
+      const valuesFile = `envs/${env}/${site}/values.yaml`;
+      const values = yaml.load(
+        await fs.readFile(await insideFile(repo, valuesFile), 'utf8'),
+      )?.['dp-connect-ui'];
+      if (
+        values?.name !== name ||
+        values?.envName !== env ||
+        !values?.image?.tag
+      )
+        throw new Error(
+          'CONNECT site values are missing the expected target identity/image.',
+        );
+      candidates.push({
+        name: `dp-${name}`,
+        enabled: true,
+        revision: 'main',
+        valueFiles: [`../${valuesFile}`],
+      });
+    } else {
+      if (!configRepoPath || !configRevision)
+        throw new Error(
+          'CORE/NEXT registration requires a checked-out target values repository and its revision.',
+        );
+      const defaults =
+        yaml.load(
+          await fs.readFile(
+            await insideFile(repo, 'apps-fleet/values.yaml'),
+            'utf8',
+          ),
+        ) || {};
+      const expectedRepo = `git@bitbucket.org:dp-cloud/gitops-${env}.git`;
+      if (
+        (fleet.gitopsRepo || defaults.gitopsRepo) !== expectedRepo ||
+        (fleet.gitopsRevision || defaults.gitopsRevision) !== configRevision
+      )
+        throw new Error(
+          'Target values checkout/revision does not match the configured fleet source.',
+        );
+      const components = requested.includes('NEXT')
+        ? ['ui', 'graphql-server']
+        : [];
+      if (requested.includes('CORE')) components.push('core');
+      for (const component of components) {
+        const valuesFile = `dp/${site}/${component}.values.yaml`;
+        const values = yaml.load(
+          await fs.readFile(
+            await insideFile(configRepoPath, valuesFile),
+            'utf8',
+          ),
+        );
+        if (!values || typeof values !== 'object' || !values.image?.tag)
+          throw new Error(
+            `Prepared target values with an image tag are required: ${valuesFile}`,
+          );
+        const allowedSecrets = [`docupace/eks/dp-${site}/${site}`];
+        if (component === 'core')
+          allowedSecrets.push(`docupace/eks/dp-core-${name}/core-secrets`);
+        if (
+          values.externalSecrets?.enabled !== true ||
+          !allowedSecrets.includes(values.externalSecrets.remoteSecretName)
+        )
+          throw new Error(
+            `Prepared target AWS ExternalSecret configuration is required: ${valuesFile}`,
+          );
+        if (
+          component === 'core' &&
+          ((values.core?.site &&
+            values.core.site !== site &&
+            values.core.site !== name) ||
+            (values.core?.environment && values.core.environment !== env))
+        )
+          throw new Error(
+            'Prepared CORE values identify a different target site/environment.',
+          );
+        const chart = {
+          ui: 'dp-ui',
+          'graphql-server': 'dp-gqs',
+          core: 'dp-core',
+        }[component];
+        await insideFile(repo, `charts/${chart}/Chart.yaml`);
+        candidates.push({
+          name: `${env}-dp-${name}-${component}`,
+          category: 'dp',
+          site: name,
+          repoURL: 'git@bitbucket.org:dp-cloud/dp-eks-next-gitops.git',
+          path: `charts/${chart}`,
+          revision: chartRevision,
+          valuesFile,
+        });
+      }
+    }
+    const existing = (fleet.projects || []).flatMap(
+      (project) => project.applications || [],
+    );
+    const added = [];
+    for (const candidate of candidates) {
+      const matches = existing.filter((app) => app.name === candidate.name);
+      if (matches.length > 1)
+        throw new Error(`Duplicate fleet application: ${candidate.name}`);
+      if (matches.length) {
+        const entry = matches[0];
+        const samePath =
+          kind === 'CONNECT'
+            ? isDeepStrictEqual(entry.valueFiles, candidate.valueFiles)
+            : entry.valuesFile === candidate.valuesFile &&
+              entry.path === candidate.path &&
+              entry.site === candidate.site &&
+              entry.category === candidate.category &&
+              entry.repoURL === candidate.repoURL;
+        if (
+          !samePath ||
+          !projects[0].applications.includes(entry) ||
+          entry.enabled === false ||
+          entry.autoSync === false
+        )
+          throw new Error(
+            `Existing fleet application conflicts or is deliberately disabled: ${candidate.name}. Review it explicitly.`,
+          );
+        if (
+          (entry.namespace && entry.namespace !== `dp-${name}`) ||
+          (entry.targetName && entry.targetName !== fleet.name) ||
+          entry.server ||
+          entry.destination ||
+          entry.valuesObject ||
+          entry.chart ||
+          entry.repo
+        )
+          throw new Error(
+            `Existing fleet application overrides its deployment target/settings: ${candidate.name}. Review it explicitly.`,
+          );
+      } else added.push(candidate);
+    }
+    const output = added.length
+      ? appendApplications(text, projectName, added)
+      : text;
+    const parsed = yaml.load(output);
+    const expected = yaml.load(text);
+    expected.projects
+      .find((project) => project.name === projectName)
+      .applications.push(...added);
+    if (!isDeepStrictEqual(parsed, expected))
+      throw new Error('Fleet append validation failed.');
+    plans.push({
+      repoPath: repo,
+      relativeFile: relative,
+      added: added.map((app) => app.name),
+      file,
+      output,
+    });
+  }
+  // All requested components and values are checked before any file is written.
+  if (!dryRun)
+    for (const plan of plans)
+      if (plan.added.length) await fs.writeFile(plan.file, plan.output);
+  return {
+    env,
+    site,
+    files: plans.map(({ repoPath, relativeFile, added }) => ({
+      repoPath,
+      relativeFile,
+      added,
+    })),
+  };
+}
+
+// CONNECT configuration sync uses strict success checks; legacy pipeline behavior is unchanged.
+const BITBUCKET_BASE_URL = 'https://api.bitbucket.org/2.0';
+const BITBUCKET_WS_URL = 'https://bitbucket.org/dp-cloud';
+
+// Repository access tokens must be sent as Bearer; the REST API rejects them as Basic x-token-auth.
+function getConnectPipelineRequestConfig() {
+  const token = process.env.CONNECT_GITOPS_PIPELINE_TOKEN;
+  if (token) return { headers: { Authorization: `Bearer ${token}` } };
+  const { username, password } = getBitbucketInfo();
+  return { auth: { username, password } };
+}
+
+async function triggerConnectPipeline(
+  repository,
+  pipelineName,
+  branch,
+  variables,
+) {
+  const { workspace } = getBitbucketInfo();
+  const url = `${BITBUCKET_BASE_URL}/repositories/${workspace}/${repository}/pipelines/`;
+
+  const payload = {
+    target: {
+      type: 'pipeline_ref_target',
+      ref_type: 'branch',
+      ref_name: branch,
+      selector: {
+        type: 'custom',
+        pattern: pipelineName,
+      },
+    },
+    variables: variables
+      ? Object.entries(variables).map(([key, value]) => ({
+          key,
+          value,
+          secured: false, // Set to true if the variable should be secure
+        }))
+      : undefined,
+  };
+
+  try {
+    const response = await axios.post(url, payload, {
+      ...getConnectPipelineRequestConfig(),
+      timeout: 30000,
+    });
+    return response.data;
+  } catch (error) {
+    console.error(
+      'Error triggering custom pipeline:',
+      error.response?.data || error.message,
+    );
+    throw error;
+  }
+}
+
+async function getConnectPipelineState(repository, pipelineUUID) {
+  const { workspace } = getBitbucketInfo();
+  const url = `${BITBUCKET_BASE_URL}/repositories/${workspace}/${repository}/pipelines/${pipelineUUID}`;
+
+  try {
+    const response = await axios.get(url, {
+      ...getConnectPipelineRequestConfig(),
+      timeout: 30000,
+    });
+    return response.data.state;
+  } catch (error) {
+    console.error(
+      'Error fetching pipeline status:',
+      error.response?.data || error.message,
+    );
+    throw error;
+  }
+}
+
+// Onboarding must not report success when the downstream config sync fails.
+export async function runPipelineChecked(
+  repository,
+  pipelineName,
+  branch,
+  variables,
+  { timeoutMs = 60 * 60 * 1000 } = {},
+) {
+  const { username, password } = getBitbucketInfo();
+  if (!process.env.CONNECT_GITOPS_PIPELINE_TOKEN && (!username || !password))
+    throw new Error(
+      'CONNECT_GITOPS_PIPELINE_TOKEN or Bitbucket API credentials are required to start the configuration sync.',
+    );
+  let pipeline;
+  try {
+    pipeline = await triggerConnectPipeline(
+      repository,
+      pipelineName,
+      branch,
+      variables,
+    );
+  } catch {
+    throw new Error(
+      `Could not start ${repository}/${pipelineName}; the GitOps merge remains committed.`,
+    );
+  }
+  const url = `${BITBUCKET_WS_URL}/${repository}/pipelines/results/${pipeline.build_number}`;
+  console.log(`Configuration sync started: ${url}`);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    let state;
+    try {
+      state = await getConnectPipelineState(repository, pipeline.uuid);
+    } catch {
+      throw new Error(
+        `Cannot confirm configuration sync status: ${url}. The GitOps merge remains committed.`,
+      );
+    }
+    console.log(
+      `Configuration sync: ${state.name}${state.result?.name ? ` / ${state.result.name}` : ''}`,
+    );
+    if (state.name === 'COMPLETED' && state.result?.name === 'SUCCESSFUL')
+      return pipeline;
+    if (!['PARSING', 'PENDING', 'IN_PROGRESS', 'RUNNING'].includes(state.name))
+      throw new Error(
+        `Configuration sync did not succeed: ${url}. The GitOps merge remains committed.`,
+      );
+    await new Promise((resolve) => setTimeout(resolve, 10000));
+  }
+  throw new Error(
+    `Timed out waiting for configuration sync: ${url}. The pipeline may still be running; the GitOps merge remains committed.`,
+  );
+}
+
+export async function syncConnectConfig({ env }) {
+  env = normalizeConnectEnvironment(env);
+  if (env === 'dev') {
+    console.log(
+      'Dev configuration sync is triggered automatically by the main push.',
+    );
+    return;
+  }
+  return runPipelineChecked(
+    CONNECT_AWS_GITOPS_REPO,
+    `sync-${env}`,
+    CONNECT_AWS_DEFAULT_BRANCH,
+  );
+}
+
+// Standalone entry points used by site-setup; importing this module does not run them.
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    const command = process.argv[2];
+    if (command === 'environment') {
+      console.log(JSON.stringify(getConnectEnvironmentConfig(process.argv[3])));
+    } else if (command === 'readiness') {
+      const { values } = parseArgs({
+        args: process.argv.slice(3),
+        options: {
+          env: { type: 'string' },
+          site: { type: 'string' },
+          'pod-identity-only': { type: 'boolean', default: false },
+        },
+      });
+      const result = await checkConnectReadiness({
+        ...values,
+        podIdentityOnly: values['pod-identity-only'],
+      });
+      if (!result.ready) {
+        console.log(
+          `SKIPPED: CONNECT ${values.env}/${values.site} is not ready. ${result.reasons.join(' ')}`,
+        );
+        process.exitCode = 3;
+      } else {
+        console.log(
+          `READY: ${result.cluster}/${result.namespace}/${result.serviceAccount}; expected role${values['pod-identity-only'] ? '' : ' and required secret fields'} confirmed.`,
+        );
+      }
+    } else if (command === 'check-image') {
+      const { values } = parseArgs({
+        args: process.argv.slice(3),
+        options: { 'values-path': { type: 'string' } },
+      });
+      await checkConnectImage({ valuesPath: values['values-path'] });
+    } else {
+      throw new Error(
+        'Expected CONNECT AWS command: environment, readiness, or check-image.',
+      );
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}