import { execFile } from "node:child_process";
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";

import {
  DEV_CODE_AGENT_PROVIDER_CONTRACT,
  inspectCodeAgentProviderManifestRefs
} from "../../internal/cloud/code-agent-contract.ts";
import { DEV_DB_ENV_CONTRACT } from "../../internal/cloud/db-contract.ts";
import { tempReportPath } from "./report-paths.mjs";
import { readStructuredFile } from "./structured-config.mjs";

const execFileAsync = promisify(execFile);
const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");

const deployPath = "deploy/deploy.yaml";
const catalogPath = "deploy/artifact-catalog.dev.json";
const workloadsPath = "deploy/k8s/base/workloads.yaml";
const artifactReportPath = tempReportPath("dev-artifacts.json");
const mutableTags = new Set(["latest", "dev", "main", "master", "prod", "production"]);
const mirrorEnvNames = [
  "HWLAB_COMMIT_ID",
  "HWLAB_IMAGE",
  "HWLAB_IMAGE_TAG",
  "HWLAB_SKILLS_COMMIT_ID",
  "HWLAB_IMAGE_DIGEST"
];
const forbiddenDeployArtifactFields = new Set(["commitId", "image", "imageTag", "digest", "sourceCommitId", "repositoryDigest", "publishState"]);
const forbiddenDeployArtifactEnv = new Set(mirrorEnvNames.concat(["HWLAB_REVISION", "HWLAB_BUILD_CREATED_AT", "HWLAB_BUILD_SOURCE"]));
const commitMirrorEnvNames = new Set(["HWLAB_COMMIT_ID", "HWLAB_SKILLS_COMMIT_ID"]);
const imageMirrorEnvNames = new Set(["HWLAB_IMAGE"]);
const tagMirrorEnvNames = new Set(["HWLAB_IMAGE_TAG"]);
const digestMirrorEnvNames = new Set(["HWLAB_IMAGE_DIGEST"]);
const tagPattern = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
const commitPattern = /^[a-f0-9]{7,40}$/;

function parseArgs(argv) {
  const args = {
    check: false,
    plan: false,
    pretty: false,
    targetRef: null,
    targetTag: null,
    promotionCommit: null,
    help: false
  };
  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === "--check") {
      args.check = true;
    } else if (arg === "--plan") {
      args.plan = true;
    } else if (arg === "--pretty") {
      args.pretty = true;
    } else if (arg === "--target-ref") {
      args.targetRef = requireValue(argv, index, arg);
      index += 1;
    } else if (arg === "--target-tag") {
      args.targetTag = requireValue(argv, index, arg);
      index += 1;
    } else if (arg === "--promotion-commit") {
      args.promotionCommit = requireValue(argv, index, arg);
      index += 1;
    } else if (arg === "--help" || arg === "-h") {
      args.help = true;
    } else {
      throw new Error(`unknown argument: ${arg}`);
    }
  }
  return args;
}

function requireValue(argv, index, arg) {
  const value = argv[index + 1];
  if (!value || value.startsWith("--")) {
    throw new Error(`${arg} requires a value`);
  }
  return value;
}

function usage() {
  return [
    "usage: node scripts/deploy-desired-state-plan.mjs [--plan] [--check] [--pretty] [--target-ref REF] [--target-tag TAG] [--promotion-commit SHA]",
    "",
    "Read-only DEV desired-state commit/image planner.",
    "",
    "Options:",
    "  --plan              explicitly request the default read-only JSON plan",
    "  --check             exit non-zero when desired-state sources are invalid, drifted, or do not match an explicit target",
    "  --pretty            print indented JSON",
    "  --target-ref REF    resolve REF with git and review promotion to its short commit tag",
    "  --target-tag TAG    review promotion to an explicit image tag without proving registry existence",
    "  --promotion-commit SHA",
    "                      require every authoritative desired-state commit/image/tag field to match this promotion commit",
    "",
    "This command reads repository files only. It does not build, pull, push, kubectl apply, restart services, or touch PROD."
  ].join("\n");
}

async function readJson(repoRoot, relativePath) {
  return readStructuredFile(repoRoot, relativePath);
}

async function readOptionalJson(repoRoot, relativePath) {
  try {
    return await readJson(repoRoot, relativePath);
  } catch {
    return null;
  }
}

function parseImageRef(image) {
  if (typeof image !== "string" || image.length === 0) {
    return { valid: false, repository: null, tag: null, reason: "image must be a non-empty string" };
  }
  if (image.includes("@")) {
    return { valid: false, repository: null, tag: null, reason: "digest-qualified image refs are not desired-state tags" };
  }
  const slashIndex = image.lastIndexOf("/");
  const colonIndex = image.lastIndexOf(":");
  if (colonIndex <= slashIndex) {
    return { valid: false, repository: image, tag: null, reason: "image ref is missing a tag" };
  }
  const repository = image.slice(0, colonIndex);
  const tag = image.slice(colonIndex + 1);
  if (!repository || !tag) {
    return { valid: false, repository, tag, reason: "image repository and tag must be non-empty" };
  }
  return { valid: true, repository, tag, reason: null };
}

function replaceImageTag(image, targetTag) {
  const parsed = parseImageRef(image);
  return parsed.valid ? `${parsed.repository}:${targetTag}` : null;
}

function shortCommit(value) {
  return typeof value === "string" && value.length >= 7 ? value.slice(0, 7) : value;
}

function commitEquivalent(actual, expected) {
  if (typeof actual !== "string" || typeof expected !== "string") return false;
  return actual === expected || actual === expected.slice(0, 7) || expected === actual.slice(0, 7);
}

function listItems(document) {
  if (!document) return [];
  return document.kind === "List" ? document.items ?? [] : [document];
}

function serviceIdForWorkload(item, container) {
  return (
    item?.metadata?.labels?.["hwlab.pikastech.local/service-id"] ||
    item?.spec?.template?.metadata?.labels?.["hwlab.pikastech.local/service-id"] ||
    container?.name ||
    item?.metadata?.name
  );
}

function workloadContainers(item) {
  return item?.spec?.template?.spec?.containers ?? [];
}

function envListToObject(envList) {
  const env = {};
  if (!Array.isArray(envList)) return env;
  for (const entry of envList) {
    if (!entry?.name) continue;
    if (Object.hasOwn(entry, "value")) {
      env[entry.name] = entry.value;
    } else if (entry.valueFrom) {
      env[entry.name] = { valueFrom: entry.valueFrom };
    }
  }
  return env;
}

function addDiagnostic(ctx, diagnostic) {
  ctx.diagnostics.push({
    severity: "blocker",
    ...diagnostic
  });
}

function addMismatch(ctx, code, sourcePath, message, expected, actual, extra = {}) {
  addDiagnostic(ctx, {
    code,
    path: sourcePath,
    message,
    expected,
    actual,
    ...extra
  });
}

function recordObservation(ctx, observation) {
  ctx.observations.push(observation);
}

function expectedEnvValue(name, service, desiredCommitId) {
  if (name === "HWLAB_COMMIT_ID" || name === "HWLAB_SKILLS_COMMIT_ID") return service?.commitId ?? service?.imageTag ?? desiredCommitId;
  if (name === "HWLAB_IMAGE") return service?.image ?? null;
  if (name === "HWLAB_IMAGE_TAG") return service?.imageTag ?? null;
  if (name === "HWLAB_IMAGE_DIGEST") return service?.digest ?? "not_published";
  return null;
}

function observationKindForEnv(name) {
  if (commitMirrorEnvNames.has(name)) return "commit";
  if (imageMirrorEnvNames.has(name)) return "image";
  if (tagMirrorEnvNames.has(name)) return "tag";
  if (digestMirrorEnvNames.has(name)) return "digest";
  return "unknown";
}

function valueMatchesExpected(kind, actual, expected) {
  if (expected === null || expected === undefined) return true;
  if (kind === "commit") return commitEquivalent(actual, expected);
  return Object.is(actual, expected);
}

function inspectEnvMirrors(ctx, { source, basePath, serviceId, env, service, desiredCommitId, requiredMirrorNames = [] }) {
  const present = {};
  const missing = [];
  const diagnostics = [];
  const required = new Set(requiredMirrorNames);

  for (const name of mirrorEnvNames) {
    if (!Object.hasOwn(env ?? {}, name)) {
      missing.push(name);
      if (required.has(name)) {
        const kind = observationKindForEnv(name);
        const expected = expectedEnvValue(name, service, desiredCommitId);
        const diagnostic = {
          code: "missing_mirror",
          path: `${basePath}.${name}`,
          message: `${source} ${serviceId} must include ${name} so DEV applies own runtime ${kind} identity`,
          expected,
          actual: null
        };
        diagnostics.push(diagnostic);
        addDiagnostic(ctx, diagnostic);
      }
      continue;
    }
    const actual = env[name];
    const kind = observationKindForEnv(name);
    const expected = expectedEnvValue(name, service, desiredCommitId);
    const record = {
      name,
      value: actual,
      expected,
      status: valueMatchesExpected(kind, actual, expected) ? "match" : "drift"
    };
    present[name] = record;
    recordObservation(ctx, {
      source,
      serviceId,
      path: `${basePath}.${name}`,
      field: name,
      kind,
      value: actual,
      expected
    });
    if (record.status === "drift") {
      const message = `${source} ${serviceId} ${name} mirror does not match desired ${kind}`;
      const diagnostic = {
        code: "mirror_mismatch",
        path: `${basePath}.${name}`,
        message,
        expected,
        actual
      };
      diagnostics.push(diagnostic);
      addDiagnostic(ctx, diagnostic);
    }
  }

  return { present, missing, diagnostics };
}

function inspectCodeAgentProviderDesiredState(ctx, deployService, workloadRecords) {
  const workloadRecord = workloadRecords.find((workload) => workload.containerName === "hwlab-cloud-api") ?? workloadRecords[0] ?? null;
  const inspection = inspectCodeAgentProviderManifestRefs({
    deployEnv: deployService?.env ?? {},
    workloadEnv: workloadRecord?.env ?? {}
  });
  if (!inspection.ready) {
    addDiagnostic(ctx, {
      code: "code_agent_provider_contract_mismatch",
      path: "deploy.codeAgentProvider",
      message: "hwlab-cloud-api desired state must preserve Code Agent provider Secret ref and DEV egress proxy env",
      expected: {
        provider: DEV_CODE_AGENT_PROVIDER_CONTRACT.codeAgentProvider,
        secretRef: `${DEV_CODE_AGENT_PROVIDER_CONTRACT.secretRefs[0].secretName}/${DEV_CODE_AGENT_PROVIDER_CONTRACT.secretRefs[0].secretKey}`,
        egressTarget: DEV_CODE_AGENT_PROVIDER_CONTRACT.egress.target
      },
      actual: {
        missingDeployEnv: inspection.missingDeployEnv,
        missingWorkloadEnv: inspection.missingWorkloadEnv,
        deployMismatches: inspection.deployMismatches.map((entry) => entry.name),
        workloadMismatches: inspection.workloadMismatches.map((entry) => entry.name),
        missingSecretRefs: inspection.missingSecretRefs,
        missingEgressContract: inspection.missingEgressContract,
        missingCodexHomeContract: inspection.missingCodexHomeContract,
        missingWorkspaceContract: inspection.missingWorkspaceContract,
        missingNoProxyContract: inspection.missingNoProxyContract,
        missingForwarderContract: inspection.missingForwarderContract
      },
      secretMaterialRead: false,
      valuesRedacted: true
    });
  }
  recordObservation(ctx, {
    source: "deploy",
    serviceId: "hwlab-cloud-api",
    path: `${deployPath}.services.hwlab-cloud-api.env.OPENAI_API_KEY`,
    field: "OPENAI_API_KEY",
    kind: "secret-ref",
    value: inspection.secretRef.present ? "secretRef:declared" : "missing_or_mismatched",
    expected: "secretRef:hwlab-code-agent-provider/openai-api-key"
  });
  recordObservation(ctx, {
    source: "workload",
    serviceId: "hwlab-cloud-api",
    path: `${workloadsPath}.hwlab-cloud-api.env.HWLAB_CODE_AGENT_OPENAI_BASE_URL`,
    field: "HWLAB_CODE_AGENT_OPENAI_BASE_URL",
    kind: "codex-api-forwarder",
    value: inspection.egress.workloadMatchesDevProxy ? "pod-local-codex-api-forwarder" : "missing_or_mismatched",
    expected: DEV_CODE_AGENT_PROVIDER_CONTRACT.egress.target
  });
  return inspection;
}

function dbSecretRefPlaceholder() {
  const ref = DEV_DB_ENV_CONTRACT.secretRefs[0];
  return `secretRef:${ref.secretName}/${ref.secretKey}`;
}

function secretRefMatches(entry, ref) {
  return (
    entry?.valueFrom?.secretKeyRef?.name === ref.secretName &&
    entry?.valueFrom?.secretKeyRef?.key === ref.secretKey
  );
}

function inspectCloudApiDbDesiredState(ctx, deployService, workloadRecords) {
  const workloadRecord = workloadRecords.find((workload) => workload.containerName === "hwlab-cloud-api") ?? workloadRecords[0] ?? null;
  const deployEnv = deployService?.env ?? {};
  const workloadEnv = workloadRecord?.env ?? {};
  const secretRef = DEV_DB_ENV_CONTRACT.secretRefs[0];
  const expectedSecretRef = dbSecretRefPlaceholder();
  const expectedSslMode = DEV_DB_ENV_CONTRACT.nonSecretDefaults.HWLAB_CLOUD_DB_SSL_MODE;
  const deploySecretMatches = deployEnv.HWLAB_CLOUD_DB_URL === expectedSecretRef;
  const workloadSecretMatches = secretRefMatches(workloadEnv.HWLAB_CLOUD_DB_URL, secretRef);
  const deploySslMatches = deployEnv.HWLAB_CLOUD_DB_SSL_MODE === expectedSslMode;
  const workloadSslMatches = workloadEnv.HWLAB_CLOUD_DB_SSL_MODE === expectedSslMode;
  const ready = deploySecretMatches && workloadSecretMatches && deploySslMatches && workloadSslMatches;

  if (!ready) {
    addDiagnostic(ctx, {
      code: "cloud_api_db_contract_mismatch",
      path: "deploy.cloudApiDb",
      message: "hwlab-cloud-api desired state must preserve DEV DB Secret ref and non-SSL runtime mode",
      expected: {
        secretRef: `${secretRef.secretName}/${secretRef.secretKey}`,
        sslMode: expectedSslMode
      },
      actual: {
        deploySecretRef: deploySecretMatches ? "secretRef:declared" : "missing_or_mismatched",
        workloadSecretRef: workloadSecretMatches ? "secretRef:declared" : "missing_or_mismatched",
        deploySslMode: deployEnv.HWLAB_CLOUD_DB_SSL_MODE ?? null,
        workloadSslMode: workloadEnv.HWLAB_CLOUD_DB_SSL_MODE ?? null
      },
      secretMaterialRead: false,
      valuesRedacted: true
    });
  }

  recordObservation(ctx, {
    source: "deploy",
    serviceId: "hwlab-cloud-api",
    path: `${deployPath}.services.hwlab-cloud-api.env.HWLAB_CLOUD_DB_SSL_MODE`,
    field: "HWLAB_CLOUD_DB_SSL_MODE",
    kind: "runtime-config",
    value: deployEnv.HWLAB_CLOUD_DB_SSL_MODE ?? null,
    expected: expectedSslMode
  });
  recordObservation(ctx, {
    source: "workload",
    serviceId: "hwlab-cloud-api",
    path: `${workloadsPath}.hwlab-cloud-api.env.HWLAB_CLOUD_DB_SSL_MODE`,
    field: "HWLAB_CLOUD_DB_SSL_MODE",
    kind: "runtime-config",
    value: workloadEnv.HWLAB_CLOUD_DB_SSL_MODE ?? null,
    expected: expectedSslMode
  });

  return {
    contractVersion: DEV_DB_ENV_CONTRACT.contractVersion,
    environment: DEV_DB_ENV_CONTRACT.environment,
    status: ready ? "pass" : "blocked",
    ready,
    secretRef: {
      env: secretRef.env,
      secretName: secretRef.secretName,
      secretKey: secretRef.secretKey,
      deployPlaceholderPresent: deploySecretMatches,
      workloadSecretRefPresent: workloadSecretMatches,
      present: deploySecretMatches && workloadSecretMatches,
      redacted: true
    },
    sslMode: {
      env: "HWLAB_CLOUD_DB_SSL_MODE",
      value: deployEnv.HWLAB_CLOUD_DB_SSL_MODE ?? null,
      workloadValue: workloadEnv.HWLAB_CLOUD_DB_SSL_MODE ?? null,
      expected: expectedSslMode,
      deployMatches: deploySslMatches,
      workloadMatches: workloadSslMatches,
      secret: false
    },
    secretMaterialRead: false,
    valuesRedacted: true,
    liveDbEvidence: false,
    fixtureEvidence: false
  };
}

function indexWorkloads(workloads) {
  const byService = new Map();
  for (const item of listItems(workloads)) {
    for (const [containerIndex, container] of workloadContainers(item).entries()) {
      const serviceId = serviceIdForWorkload(item, container);
      if (!serviceId) continue;
      const record = {
        kind: item?.kind ?? "unknown",
        name: item?.metadata?.name ?? "unknown",
        namespace: item?.metadata?.namespace ?? null,
        containerIndex,
        containerName: container?.name ?? "unknown",
        image: container?.image ?? null,
        env: {
          ...envListToObject(container?.env),
          __volumeMounts: Array.isArray(container?.volumeMounts) ? container.volumeMounts : [],
          __volumes: Array.isArray(item?.spec?.template?.spec?.volumes) ? item.spec.template.spec.volumes : [],
          __podContainers: Array.isArray(item?.spec?.template?.spec?.containers) ? item.spec.template.spec.containers : [],
          __initContainers: Array.isArray(item?.spec?.template?.spec?.initContainers) ? item.spec.template.spec.initContainers : [],
          __deploymentStrategy: item?.spec?.strategy ?? null
        },
        path: `${workloadsPath}.${item?.kind ?? "Workload"}.${item?.metadata?.name ?? serviceId}.containers[${containerIndex}]`
      };
      const list = byService.get(serviceId) ?? [];
      list.push(record);
      byService.set(serviceId, list);
    }
  }
  return byService;
}

function serviceIdsFrom(...sources) {
  const ids = [];
  for (const source of sources) {
    for (const id of source) {
      if (typeof id === "string" && id.length > 0 && !ids.includes(id)) ids.push(id);
    }
  }
  return ids;
}

function assertTargetTag(ctx, tag, pathName) {
  if (!tagPattern.test(tag)) {
    addMismatch(ctx, "invalid_target_tag", pathName, "target tag is not a valid Docker tag", "Docker tag syntax", tag);
  }
  if (mutableTags.has(tag)) {
    addMismatch(ctx, "mutable_target_tag", pathName, `target tag ${tag} is mutable and forbidden for desired-state pinning`, "immutable tag", tag);
  }
}

async function resolveTarget(repoRoot, { targetRef, targetTag, promotionCommit, requireTargetConvergence = false }, ctx) {
  if (!targetRef && !targetTag && !promotionCommit) return null;
  let commitId = null;
  let shortCommitId = null;
  let acceptedCurrentMain = null;
  if (targetRef) {
    try {
      const result = await execFileAsync("git", ["rev-parse", "--verify", `${targetRef}^{commit}`], { cwd: repoRoot });
      commitId = result.stdout.trim();
      shortCommitId = commitId.slice(0, 7);
    } catch (error) {
      addDiagnostic(ctx, {
        code: "target_ref_unresolved",
        path: "--target-ref",
        message: `target ref ${targetRef} could not be resolved with git`,
        expected: "local git ref",
        actual: error instanceof Error ? error.message : String(error)
      });
    }
  }
  if (promotionCommit) {
    if (!commitPattern.test(String(promotionCommit))) {
      addMismatch(ctx, "invalid_promotion_commit", "--promotion-commit", "promotion commit must be a short or full lowercase Git SHA", "7-40 lowercase hex", promotionCommit);
    } else {
      const promotionShortCommitId = promotionCommit.slice(0, 7);
      if (commitId && !commitEquivalent(promotionCommit, commitId)) {
        addMismatch(ctx, "promotion_commit_ref_mismatch", "--promotion-commit", "promotion commit must match the resolved target ref", commitId, promotionCommit);
      }
      commitId = commitId ?? promotionCommit;
      shortCommitId = shortCommitId ?? promotionShortCommitId;
    }
  }
  const tag = targetTag ?? shortCommitId;
  if (tag) assertTargetTag(ctx, tag, "--target-tag");
  if (promotionCommit && commitPattern.test(String(promotionCommit)) && targetTag && targetTag !== promotionCommit.slice(0, 7)) {
    addMismatch(ctx, "promotion_tag_mismatch", "--target-tag", "promotion target tag must be the short promotion commit", promotionCommit.slice(0, 7), targetTag);
  }
  const requireConvergence = Boolean(promotionCommit || requireTargetConvergence);
  if (targetRef && commitId && requireConvergence && !promotionCommit && !targetTag) {
    acceptedCurrentMain = await resolveAcceptedCurrentMain(repoRoot, commitId);
  }
  const comparisonCommitId = acceptedCurrentMain?.commitId ?? commitId;
  const comparisonTag = acceptedCurrentMain?.tag ?? tag;
  return {
    targetRef,
    promotionCommit,
    commitId,
    shortCommitId,
    tag,
    tagSource: targetTag ? "target-tag" : promotionCommit ? "promotion-commit-short" : "target-ref-short-commit",
    acceptedCurrentMain,
    comparisonCommitId,
    comparisonTag,
    requireConvergence,
    convergenceRequirement: promotionCommit ? "promotion-commit" : requireTargetConvergence ? "target-check" : "plan-only"
  };
}

async function resolveAcceptedCurrentMain(repoRoot, targetCommitId) {
  try {
    const [{ stdout: headStdout }, { stdout: parentsStdout }] = await Promise.all([
      execFileAsync("git", ["rev-parse", "--verify", "HEAD^{commit}"], { cwd: repoRoot }),
      execFileAsync("git", ["rev-list", "--parents", "-n", "1", targetCommitId], { cwd: repoRoot })
    ]);
    const headCommitId = headStdout.trim();
    if (headCommitId !== targetCommitId) return null;

    const [commitId, firstParentId, secondParentId] = parentsStdout.trim().split(/\s+/u);
    if (commitId !== targetCommitId || !firstParentId || !secondParentId) return null;

    return {
      mode: "target-ref-head-merge-first-parent",
      reason: "A merged main commit cannot contain desired-state files pinned to its own content hash; compare against the accepted first-parent main commit.",
      commitId: firstParentId,
      shortCommitId: firstParentId.slice(0, 7),
      tag: firstParentId.slice(0, 7)
    };
  } catch {
    return null;
  }
}

function targetLabel(target) {
  if (target.acceptedCurrentMain) return `${target.targetRef} accepted first parent (${target.acceptedCurrentMain.tag})`;
  if (target.targetRef && target.tag) return `${target.targetRef} (${target.tag})`;
  if (target.promotionCommit) return target.promotionCommit;
  if (target.tag) return `tag ${target.tag}`;
  return "target";
}

function observationMatchesTarget(observation, target) {
  if (!target) return null;
  if (observation.kind === "commit") {
    return target.comparisonCommitId ? commitEquivalent(observation.value, target.comparisonCommitId) : null;
  }
  if (observation.kind === "tag") {
    return target.comparisonTag ? observation.value === target.comparisonTag : null;
  }
  if (observation.kind === "image") {
    return target.comparisonTag ? parseImageRef(observation.value).tag === target.comparisonTag : null;
  }
  return null;
}

function buildTargetConvergence(ctx, target) {
  if (!target) return null;
  if (target.targetRef && !target.commitId) {
    return {
      state: "target_unresolved",
      comparableFields: 0,
      matchingTargetFields: 0,
      pendingTargetFields: 0,
      matchingPaths: [],
      pendingPaths: []
    };
  }
  const comparable = ctx.observations
    .map((observation) => ({
      ...observation,
      matchesTarget: observationMatchesTarget(observation, target)
    }))
    .filter((observation) => observation.matchesTarget !== null);
  const matching = comparable.filter((observation) => observation.matchesTarget === true);
  const pending = comparable.filter((observation) => observation.matchesTarget === false);
  const partial = matching.length > 0 && pending.length > 0;
  const promotionRequired = target.requireConvergence === true;

  if (partial) {
    addDiagnostic(ctx, {
      code: "partial_target_drift",
      path: "desired-state",
      message: "desired-state fields partially match the target while other authoritative fields still point elsewhere",
      expected: target.tag,
      actual: {
        matching: matching.length,
        pending: pending.length
      }
    });
  } else if (promotionRequired && pending.length > 0) {
    const promotionCommitRequired = Boolean(target.promotionCommit);
    addDiagnostic(ctx, {
      code: promotionCommitRequired ? "promotion_commit_mismatch" : "target_desired_state_mismatch",
      path: "desired-state",
      message: promotionCommitRequired
        ? "desired-state fields do not match the required promotion commit/tag"
        : `stale artifact catalog is not pinned to ${targetLabel(target)}; explicit target checks require current-main/commit-pinned catalog identity`,
      expected: {
        commitId: target.comparisonCommitId,
        imageTag: target.comparisonTag
      },
      actual: {
        pending: pending.length,
        samplePendingPaths: pending.slice(0, 8).map((item) => item.path)
      }
    });
  }

  const state = partial
    ? "partial_drift"
    : pending.length === 0
      ? target.acceptedCurrentMain
        ? "accepted_main_promoted"
        : "already_promoted"
      : promotionRequired
        ? target.promotionCommit
          ? "promotion_mismatch"
          : "target_mismatch"
        : "promotion_pending";
  return {
    state,
    comparableFields: comparable.length,
    matchingTargetFields: matching.length,
    pendingTargetFields: pending.length,
    matchingPaths: matching.map((item) => item.path),
    pendingPaths: pending.map((item) => item.path)
  };
}

function reportHints(report, desiredCommitId) {
  if (!report) {
    return {
      path: artifactReportPath,
      present: false,
      authoritative: false,
      note: "optional report snapshot is absent; desired-state review still uses deploy files only"
    };
  }
  const artifactPublish = report.artifactPublish ?? {};
  const reportCommitId = report.commitId ?? null;
  const artifactSourceCommitId = artifactPublish.sourceCommitId ?? null;
  return {
    path: artifactReportPath,
    present: true,
    authoritative: false,
    note: "temporary publish JSON is contextual evidence only; deploy desired-state remains authoritative in deploy/",
    commitId: reportCommitId,
    matchesDesiredState: reportCommitId ? commitEquivalent(reportCommitId, desiredCommitId) : null,
    artifactPublish: {
      status: artifactPublish.status ?? null,
      sourceCommitId: artifactSourceCommitId,
      sourceMatchesDesiredState: artifactSourceCommitId ? commitEquivalent(artifactSourceCommitId, desiredCommitId) : null,
      publishedCount: artifactPublish.publishedCount ?? null,
      serviceCount: artifactPublish.serviceCount ?? null,
      registryVerified: artifactPublish.registryVerified ?? null,
      registryCapabilitiesClassification: artifactPublish.registryCapabilities?.classification ?? null
    }
  };
}

function servicePromotion(service, target) {
  const targetTag = target?.comparisonTag ?? target?.tag;
  if (!targetTag) return null;
  return {
    targetCommitId: target.comparisonCommitId ?? target.commitId,
    targetImageTag: targetTag,
    deployImage: null,
    catalogImage: service.catalog?.image ? replaceImageTag(service.catalog.image, targetTag) : null,
    workloadImages: (service.workloads ?? []).map((workload) => ({
      workload: workload.name,
      container: workload.container,
      image: workload.image ? replaceImageTag(workload.image, targetTag) : null
    }))
  };
}

function targetCommands(target) {
  if (!target?.targetRef && !target?.promotionCommit) return [];
  const commands = [];
  if (target.promotionCommit) {
    commands.push(`node scripts/deploy-desired-state-plan.mjs --promotion-commit ${target.promotionCommit} --check --pretty`);
  }
  if (target.targetRef) {
    commands.push(
    `node scripts/deploy-desired-state-plan.mjs --target-ref ${target.targetRef} --pretty`,
    `node scripts/refresh-artifact-catalog.mjs --target-ref ${target.targetRef} --blocked --no-write`,
    `node scripts/refresh-artifact-catalog.mjs --target-ref ${target.targetRef} --publish-report ${artifactReportPath} --no-write`
    );
  }
  return commands;
}

export async function buildDesiredStatePlan(options = {}) {
  const repoRoot = options.repoRoot ?? defaultRepoRoot;
  const ctx = { diagnostics: [], observations: [] };
  const [deploy, catalog, workloads, artifactReport] = await Promise.all([
    readJson(repoRoot, deployPath),
    readJson(repoRoot, catalogPath),
    readJson(repoRoot, workloadsPath),
    readOptionalJson(repoRoot, artifactReportPath)
  ]);
  const target = await resolveTarget(repoRoot, {
    targetRef: options.targetRef ?? null,
    targetTag: options.targetTag ?? null,
    promotionCommit: options.promotionCommit ?? null,
    requireTargetConvergence: options.requireTargetConvergence === true
  }, ctx);

  const deployServices = deploy.services ?? [];
  const catalogServices = catalog.services ?? [];
  const deployByService = new Map(deployServices.map((service) => [service.serviceId, service]));
  const catalogByService = new Map(catalogServices.map((service) => [service.serviceId, service]));
  const workloadByService = indexWorkloads(workloads);
  const desiredCommitId = catalog.commitId;
  const desiredImageTag = shortCommit(desiredCommitId);

  recordObservation(ctx, {
    source: "catalog",
    path: `${catalogPath}.commitId`,
    field: "commitId",
    kind: "commit",
    value: catalog.commitId,
    expected: desiredCommitId
  });

  if (Object.hasOwn(deploy, "commitId")) {
    addMismatch(ctx, "generated_artifact_identity", `${deployPath}.commitId`, "deploy.yaml is human-authored config; generated commit identity must stay in artifact catalog", "absent", deploy.commitId);
  }
  if (!commitPattern.test(String(catalog.commitId ?? ""))) {
    addMismatch(ctx, "invalid_commit", `${catalogPath}.commitId`, "artifact catalog commitId must be a short or full lowercase Git SHA", "7-40 lowercase hex", catalog.commitId);
  }

  const serviceIds = serviceIdsFrom(
    deployServices.map((service) => service.serviceId),
    catalogServices.map((service) => service.serviceId),
    [...workloadByService.keys()]
  );

  const services = [];
  let codeAgentProvider = null;
  let cloudApiDb = null;
  for (const serviceId of serviceIds) {
    const deployService = deployByService.get(serviceId);
    const catalogService = catalogByService.get(serviceId);
    const workloadsForService = workloadByService.get(serviceId) ?? [];
    const service = {
      serviceId,
      deploy: null,
      catalog: null,
      workloads: [],
      promotion: null
    };

    if (!deployService) {
      addMismatch(ctx, "missing_service", `${deployPath}.services.${serviceId}`, `${serviceId} missing from deploy manifest`, "service entry", null, { serviceId });
    }
    if (!catalogService) {
      addMismatch(ctx, "missing_service", `${catalogPath}.services.${serviceId}`, `${serviceId} missing from artifact catalog`, "service entry", null, { serviceId });
    }
    if (!workloadsForService.length) {
      addMismatch(ctx, "missing_workload", `${workloadsPath}.${serviceId}`, `${serviceId} missing from k8s workloads`, "workload container", null, { serviceId });
    }

    const catalogImage = parseImageRef(catalogService?.image);
    const serviceImageTag = catalogService?.imageTag ?? catalogImage.tag ?? desiredImageTag;
    const serviceCommitId = catalogService?.commitId ?? serviceImageTag;
    if (deployService) {
      const deployPathBase = `${deployPath}.services.${serviceId}`;
      for (const field of Object.keys(deployService)) {
        if (forbiddenDeployArtifactFields.has(field)) {
          addMismatch(ctx, "generated_artifact_identity", `${deployPathBase}.${field}`, `${serviceId} deploy service field is generated artifact identity and must stay in artifact catalog`, "absent", deployService[field], { serviceId });
        }
      }
      for (const envName of Object.keys(deployService.env ?? {})) {
        if (forbiddenDeployArtifactEnv.has(envName)) {
          addMismatch(ctx, "generated_artifact_identity", `${deployPathBase}.env.${envName}`, `${serviceId} deploy env is generated artifact identity and must be rendered from artifact catalog`, "absent", deployService.env[envName], { serviceId });
        }
      }
      service.deploy = {
        artifactIdentity: "human-authored-config",
        envMirrors: inspectEnvMirrors(ctx, {
          source: "deploy",
          basePath: `${deployPathBase}.env`,
          serviceId,
          env: deployService.env ?? {},
          service: null,
          desiredCommitId: null,
          requiredMirrorNames: []
        })
      };
    }

    if (catalogService) {
      const catalogPathBase = `${catalogPath}.services.${serviceId}`;
      recordObservation(ctx, {
        source: "catalog",
        serviceId,
        path: `${catalogPathBase}.commitId`,
        field: "commitId",
        kind: "commit",
        value: catalogService.commitId,
        expected: serviceCommitId
      });
      recordObservation(ctx, {
        source: "catalog",
        serviceId,
        path: `${catalogPathBase}.image`,
        field: "image",
        kind: "image",
        value: catalogService.image,
        expected: catalogService.image
      });
      recordObservation(ctx, {
        source: "catalog",
        serviceId,
        path: `${catalogPathBase}.imageTag`,
        field: "imageTag",
        kind: "tag",
        value: catalogService.imageTag,
        expected: serviceImageTag
      });
      if (!commitPattern.test(String(catalogService.commitId ?? ""))) {
        addMismatch(ctx, "invalid_commit", `${catalogPathBase}.commitId`, `${serviceId} catalog service commitId must be a short or full lowercase Git SHA`, "7-40 lowercase hex", catalogService.commitId, { serviceId });
      } else if (!commitEquivalent(catalogService.commitId, serviceImageTag)) {
        addMismatch(ctx, "commit_mismatch", `${catalogPathBase}.commitId`, `${serviceId} catalog service commitId must match service artifact tag`, serviceImageTag, catalogService.commitId, { serviceId });
      }
      if (!catalogImage.valid) {
        addMismatch(ctx, "invalid_image", `${catalogPathBase}.image`, catalogImage.reason, "tagged image ref", catalogService.image, { serviceId });
      }
      if (catalogService.imageTag !== serviceImageTag) {
        addMismatch(ctx, "image_tag_mismatch", `${catalogPathBase}.imageTag`, `${serviceId} catalog imageTag must match service artifact tag`, serviceImageTag, catalogService.imageTag, { serviceId });
      }
      if (catalogImage.valid && catalogImage.tag !== catalogService.imageTag) {
        addMismatch(ctx, "image_tag_mismatch", `${catalogPathBase}.image`, `${serviceId} catalog image tag must match catalog imageTag`, catalogService.imageTag, catalogImage.tag, { serviceId });
      }
      service.catalog = {
        commitId: catalogService.commitId,
        image: catalogService.image,
        imageTag: catalogService.imageTag,
        digest: catalogService.digest,
        publishState: catalogService.publishState,
        artifactRequired: catalogService.artifactRequired
      };
    }

    for (const workload of workloadsForService) {
      const workloadImage = parseImageRef(workload.image);
      recordObservation(ctx, {
        source: "workload",
        serviceId,
        path: `${workload.path}.image`,
        field: "image",
        kind: "image",
        value: workload.image,
        expected: catalogService?.image ?? null
      });
      if (!workloadImage.valid) {
        addMismatch(ctx, "invalid_image", `${workload.path}.image`, workloadImage.reason, "tagged image ref", workload.image, { serviceId });
      }
      service.workloads.push({
        kind: workload.kind,
        name: workload.name,
        namespace: workload.namespace,
        container: workload.containerName,
        image: workload.image,
        imageTag: workloadImage.tag,
        envMirrors: inspectEnvMirrors(ctx, {
          source: "workload",
          basePath: `${workload.path}.env`,
          serviceId,
          env: workload.env,
          service: null,
          desiredCommitId: null,
          requiredMirrorNames: []
        })
      });
    }

    service.promotion = servicePromotion(service, target);
    services.push(service);

    if (serviceId === "hwlab-cloud-api") {
      cloudApiDb = inspectCloudApiDbDesiredState(ctx, deployService, workloadsForService);
      codeAgentProvider = inspectCodeAgentProviderDesiredState(ctx, deployService, workloadsForService);
    }
  }

  const targetConvergence = buildTargetConvergence(ctx, target);
  const blockers = ctx.diagnostics.filter((diagnostic) => diagnostic.severity === "blocker");
  const status = blockers.length > 0
    ? "blocked"
    : targetConvergence?.state === "promotion_pending"
      ? "planned"
      : "pass";

  const presentMirrorCount = services.reduce((count, service) => {
    const deployCount = service.deploy ? Object.keys(service.deploy.envMirrors.present).length : 0;
    const workloadCount = service.workloads.reduce((inner, workload) => inner + Object.keys(workload.envMirrors.present).length, 0);
    return count + deployCount + workloadCount;
  }, 0);

  return {
    kind: "hwlab-deploy-desired-state-plan",
    mode: "read-only-plan",
    status,
    source: {
      deploy: deployPath,
      artifactCatalog: catalogPath,
      workloads: workloadsPath,
      optionalReport: artifactReportPath
    },
    safety: {
      readOnly: true,
      sourceOrDryRunSupportOnly: true,
      kubectlApply: false,
      registryPull: false,
      registryPush: false,
      imageBuild: false,
      serviceRestart: false,
      prod: false,
      devLiveClaim: false
    },
    checkSemantics: "--check exits non-zero for missing/invalid desired-state sources, generated artifact identity leaking into deploy.yaml, invalid target tags, partial target drift, or catalog identity mismatch with an explicit --target-ref, --target-tag, or --promotion-commit. When the checked target ref is the current checked-out merge commit, the comparable current-main target is its accepted first parent because a commit cannot embed its own content hash. Without --check, a uniform older catalog under --target-ref/--target-tag is a read-only promotion plan.",
    summary: {
      desiredCommitId,
      desiredImageTag,
      artifactState: catalog.artifactState,
      ciPublished: catalog.publish?.ciPublished === true,
      registryVerified: catalog.publish?.registryVerified === true,
      services: services.length,
      workloadContainers: [...workloadByService.values()].reduce((sum, entries) => sum + entries.length, 0),
      presentMirrorCount,
      diagnostics: ctx.diagnostics.length,
      blockers: blockers.length,
      targetConvergence: targetConvergence?.state ?? "not_requested"
    },
    target: target ? {
      ...target,
      convergence: targetConvergence,
      commands: targetCommands(target)
    } : null,
    promotionBoundary: {
      writes: [],
      authoritativeDesiredState: [deployPath, catalogPath, workloadsPath],
      humanAuthoredTruth: [deployPath, workloadsPath],
      artifactIdentityTruth: [catalogPath],
      nonAuthoritativeEvidence: [artifactReportPath],
      note: "This planner is read-only. deploy.yaml is human-authored config; artifact-catalog carries generated image identity and is written by G14 Tekton promotion only to G14-gitops. It does not prove image existence, registry reachability, a real DEV apply, or M3 DEV-LIVE hardware-loop evidence."
    },
    cloudApiDb: cloudApiDb ?? {
      status: "blocked",
      ready: false,
      secretMaterialRead: false,
      valuesRedacted: true,
      liveDbEvidence: false
    },
    codeAgentProvider: codeAgentProvider ?? {
      status: "blocked",
      ready: false,
      missingDeployEnv: ["hwlab-cloud-api"],
      missingWorkloadEnv: ["hwlab-cloud-api"],
      secretMaterialRead: false,
      valuesRedacted: true
    },
    reportHints: reportHints(artifactReport, desiredCommitId),
    services,
    diagnostics: ctx.diagnostics
  };
}

export async function runDeployDesiredStatePlanCli(argv = process.argv.slice(2), options = {}) {
  const args = parseArgs(argv);
  if (args.help) {
    process.stdout.write(`${usage()}\n`);
    return;
  }
  const plan = await buildDesiredStatePlan({
    repoRoot: options.repoRoot,
    targetRef: args.targetRef,
    targetTag: args.targetTag,
    promotionCommit: args.promotionCommit,
    requireTargetConvergence: args.check && Boolean(args.targetRef || args.targetTag)
  });
  process.stdout.write(`${JSON.stringify(plan, null, args.pretty ? 2 : 0)}\n`);
  if (args.check && plan.status === "blocked") {
    process.exitCode = 1;
  }
}

export function writeDeployDesiredStatePlanError(error) {
  process.stdout.write(`${JSON.stringify({
    kind: "hwlab-deploy-desired-state-plan",
    mode: "read-only-plan",
    status: "error",
    error: error instanceof Error ? error.message : String(error),
    safety: {
      readOnly: true,
      kubectlApply: false,
      registryPull: false,
      registryPush: false,
      imageBuild: false,
      serviceRestart: false,
      prod: false,
      devLiveClaim: false
    }
  })}\n`);
  process.exitCode = 1;
}