import { createHash, randomUUID } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import { resolveArchiveDescriptions } from "./flight-text.mjs";
import { fileURLToPath } from "node:url";

export const COA_ARCHIVE = Object.freeze({
  repository: "srhinos/coa-datamine",
  revision: "5078f9ac22541c45c17a866c23aac6c12073de23",
  shortRevision: "5078f9ac2254",
  capturedAt: "2026-08-12T21:02:51+00:00",
  fetchManifestPath: "raw/talents/_fetch.json",
  builderSnapshotPath: "raw/talents/coa-builder-voljin.html",
  builderSnapshotSha256: "41a6ccd393c0648ae2b1fdc34fe94955d4fd13c0cd59040ad3860e64a8ff6c7a",
});

const defaultProjectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
const expectedClassCount = 21;
const cacheSchemaVersion = 1;
const manifestName = "manifest.json";

function assertSafeRelativePath(value, context = "archive path") {
  if (typeof value !== "string" || value.length === 0) {
    throw new Error(`${context} must be a non-empty string`);
  }
  const normalized = value.replaceAll("\\", "/");
  if (normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) {
    throw new Error(`${context} must be relative: ${value}`);
  }
  if (normalized.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
    throw new Error(`${context} contains an unsafe path segment: ${value}`);
  }
  return normalized;
}

function classFileFromDescriptor(descriptor) {
  let candidate = null;
  if (typeof descriptor === "string") {
    candidate = descriptor;
  } else if (descriptor && typeof descriptor === "object") {
    candidate = descriptor.path ?? descriptor.file ?? descriptor.filename ?? descriptor.href ?? null;
    if (candidate === null) candidate = descriptor.slug ?? descriptor.key ?? descriptor.id ?? null;
  }
  if (candidate === null || candidate === undefined) {
    throw new Error("CoA talent class index contains an entry without a file path or class key");
  }

  const relative = assertSafeRelativePath(String(candidate), "CoA talent class file reference");
  let filePath;
  if (relative.startsWith("data/talents/coa/classes/")) {
    filePath = relative;
  } else if (relative.startsWith("classes/")) {
    filePath = `data/talents/coa/${relative}`;
  } else if (relative.startsWith("data/talents/coa/") && !relative.slice("data/talents/coa/".length).includes("/")) {
    filePath = relative;
  } else if (relative.includes("/")) {
    throw new Error(`CoA talent class file is outside the indexed CoA talent data: ${candidate}`);
  } else {
    filePath = `data/talents/coa/${relative.endsWith(".json") ? relative : `${relative}.json`}`;
  }
  if (!filePath.startsWith("data/talents/coa/") || !filePath.endsWith(".json")
    || filePath === "data/talents/coa/index.json"
    || filePath === "data/talents/coa/_meta.json") {
    throw new Error(`CoA talent class file is outside the indexed CoA talent data: ${candidate}`);
  }
  return filePath;
}

function isClassArchivePath(filePath) {
  return filePath.startsWith("data/talents/coa/")
    && filePath.endsWith(".json")
    && filePath !== "data/talents/coa/index.json"
    && filePath !== "data/talents/coa/_meta.json";
}

function descriptorsFromIndex(index) {
  const entries = index?.classes;
  if (Array.isArray(entries)) return entries;
  if (entries && typeof entries === "object") {
    return Object.entries(entries).map(([key, value]) => {
      if (typeof value === "string") return value;
      if (value && typeof value === "object") return { key, ...value };
      return { key };
    });
  }
  throw new Error("CoA talent index has no classes array or object");
}

function classPathsFromIndex(index) {
  const descriptors = descriptorsFromIndex(index);
  if (descriptors.length !== expectedClassCount) {
    throw new Error(`CoA talent index expected ${expectedClassCount} class files, found ${descriptors.length}`);
  }
  const paths = descriptors.map(classFileFromDescriptor);
  if (new Set(paths).size !== expectedClassCount) {
    throw new Error("CoA talent index contains duplicate class file references");
  }
  return paths;
}

function sha256(bytes) {
  return createHash("sha256").update(bytes).digest("hex");
}

function gitBlobSha(bytes) {
  return createHash("sha1")
    .update(Buffer.from(`blob ${bytes.byteLength}\0`, "utf8"))
    .update(bytes)
    .digest("hex");
}

function parseJson(bytes, filePath) {
  try {
    return JSON.parse(bytes.toString("utf8"));
  } catch (error) {
    throw new Error(`CoA archive JSON is invalid at ${filePath}: ${error.message}`, { cause: error });
  }
}

function isRegularBlob(entry) {
  return entry?.type === "blob" && entry?.mode === "100644" && /^[0-9a-f]{40}$/i.test(entry.sha ?? "");
}

export function createSupplementCacheApi(archiveInput = COA_ARCHIVE) {
  const archive = Object.freeze({ ...archiveInput });
  for (const key of ["repository", "revision", "shortRevision", "capturedAt", "fetchManifestPath", "builderSnapshotPath", "builderSnapshotSha256"]) {
    if (typeof archive[key] !== "string" || archive[key].length === 0) {
      throw new TypeError(`archive.${key} must be a non-empty string`);
    }
  }
  if (!/^[0-9a-f]{40}$/i.test(archive.revision) || !/^[0-9a-f]{7,40}$/i.test(archive.shortRevision)) {
    throw new TypeError("archive revision values must be hexadecimal Git revisions");
  }
  if (!/^[0-9a-f]{64}$/i.test(archive.builderSnapshotSha256)) {
    throw new TypeError("archive.builderSnapshotSha256 must be a SHA-256 hex digest");
  }

  const requiredPaths = [
    archive.fetchManifestPath,
    archive.builderSnapshotPath,
    "data/talents/coa/index.json",
    "data/talents/coa/_meta.json",
    "raw/provenance.json",
    "raw/_snapshot.json",
    "data/spells/_meta.json",
  ];

  function archiveDirectory(cacheRoot) {
    if (typeof cacheRoot !== "string" || cacheRoot.length === 0) {
      throw new TypeError("cacheRoot must be a non-empty directory path");
    }
    return path.join(path.resolve(cacheRoot), `archive-${archive.shortRevision}`);
  }

  function archiveUrls(filePath) {
    const apiUrl = `https://api.github.com/repos/${archive.repository}/git/trees/${archive.revision}?recursive=1`;
    const rawPath = filePath.split("/").map(encodeURIComponent).join("/");
    const rawUrl = `https://raw.githubusercontent.com/${archive.repository}/${archive.revision}/${rawPath}`;
    return { apiUrl, rawUrl };
  }

  function parseCaptureManifest(bytes) {
    const capture = parseJson(bytes, archive.fetchManifestPath);
    if (capture?.capturedUtc !== archive.capturedAt) {
      throw new Error(`CoA capture manifest has an unexpected capture time: ${String(capture?.capturedUtc)}`);
    }
    if (capture?.savedAs !== path.posix.basename(archive.builderSnapshotPath)) {
      throw new Error(`CoA capture manifest has an unexpected savedAs value: ${String(capture?.savedAs)}`);
    }
    if (capture?.sha256 !== archive.builderSnapshotSha256) {
      throw new Error(`CoA capture manifest does not pin builder SHA-256 ${archive.builderSnapshotSha256}`);
    }
    return capture;
  }

  function sourceRecord() {
    return {
      repository: `https://github.com/${archive.repository}`,
      revision: archive.revision,
      capturedAt: archive.capturedAt,
      captureManifestPath: archive.fetchManifestPath,
      builderSnapshotPath: archive.builderSnapshotPath,
      builderSnapshotSha256: archive.builderSnapshotSha256,
    };
  }

  function validateManifestShape(manifest) {
    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
      throw new Error("CoA supplement manifest is not an object");
    }
    if (manifest.schemaVersion !== cacheSchemaVersion) {
      throw new Error(`Unsupported CoA supplement cache schema: ${String(manifest.schemaVersion)}`);
    }
    if (manifest.source?.revision !== archive.revision) {
      throw new Error("CoA supplement manifest points at an unexpected archive revision");
    }
    if (typeof manifest.generation !== "string" || !/^generation-[0-9a-f-]+$/.test(manifest.generation)) {
      throw new Error("CoA supplement manifest has an invalid generation name");
    }
    if (!Array.isArray(manifest.files)) throw new Error("CoA supplement manifest has no file list");
    const source = manifest.source;
    if (source.captureManifestPath !== archive.fetchManifestPath
      || source.builderSnapshotPath !== archive.builderSnapshotPath
      || source.builderSnapshotSha256 !== archive.builderSnapshotSha256
      || source.capturedAt !== archive.capturedAt) {
      throw new Error("CoA supplement manifest has unexpected capture metadata");
    }
  }

  function expectedFilesFromManifest(manifest) {
    validateManifestShape(manifest);
    const expected = new Map();
    for (const file of manifest.files) {
      const filePath = assertSafeRelativePath(file?.path, "CoA supplement manifest file path");
      if (expected.has(filePath)) throw new Error(`CoA supplement manifest repeats ${filePath}`);
      if (!/^[0-9a-f]{40}$/i.test(file.gitBlobSha ?? "")) {
        throw new Error(`CoA supplement manifest has an invalid Git blob SHA for ${filePath}`);
      }
      if (!/^[0-9a-f]{64}$/i.test(file.sha256 ?? "")) {
        throw new Error(`CoA supplement manifest has an invalid SHA-256 for ${filePath}`);
      }
      if (!Number.isSafeInteger(file.size) || file.size < 0) {
        throw new Error(`CoA supplement manifest has an invalid size for ${filePath}`);
      }
      expected.set(filePath, file);
    }
    for (const filePath of requiredPaths) {
      if (!expected.has(filePath)) throw new Error(`CoA supplement manifest is missing ${filePath}`);
    }
    const classPaths = [...expected.keys()].filter(isClassArchivePath);
    if (classPaths.length !== expectedClassCount || expected.size !== requiredPaths.length + expectedClassCount) {
      throw new Error(`CoA supplement manifest must contain ${expectedClassCount} class files and ${requiredPaths.length} required files`);
    }
    return expected;
  }

  async function responseBytes(fetchImpl, url, accept) {
    let response;
    try {
      response = await fetchImpl(url, { headers: { Accept: accept } });
    } catch (error) {
      throw new Error(`CoA supplemental source unavailable at ${url}: ${error.message}`, { cause: error });
    }
    if (!response || response.ok !== true) {
      const status = response?.status === undefined ? "no response" : `HTTP ${response.status}`;
      throw new Error(`CoA supplemental source unavailable at ${url} (${status})`);
    }
    try {
      if (typeof response.arrayBuffer === "function") return Buffer.from(await response.arrayBuffer());
      if (typeof response.text === "function") return Buffer.from(await response.text(), "utf8");
    } catch (error) {
      throw new Error(`CoA supplemental source read failed at ${url}: ${error.message}`, { cause: error });
    }
    throw new Error(`CoA supplemental source response has no readable body at ${url}`);
  }

  async function fetchTree(fetchImpl) {
    const { apiUrl } = archiveUrls(archive.fetchManifestPath);
    const bytes = await responseBytes(fetchImpl, apiUrl, "application/vnd.github+json");
    const treeDocument = parseJson(bytes, "GitHub archive tree");
    if (treeDocument.truncated === true) {
      throw new Error("CoA archive tree was truncated; refusing an incomplete supplemental cache");
    }
    if (!Array.isArray(treeDocument.tree)) throw new Error("CoA archive tree response does not contain a tree array");
    return new Map(treeDocument.tree.map((entry) => [entry.path, entry]));
  }

  function expectedFile(tree, filePath) {
    const safePath = assertSafeRelativePath(filePath);
    const entry = tree.get(safePath);
    if (!isRegularBlob(entry)) throw new Error(`Pinned CoA archive tree is missing a regular file at ${safePath}`);
    if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
      throw new Error(`Pinned CoA archive tree has no valid file size for ${safePath}`);
    }
    return { path: safePath, gitBlobSha: entry.sha.toLowerCase(), size: entry.size };
  }

  async function readManifest(archiveRoot) {
    try {
      return parseJson(await fs.readFile(path.join(archiveRoot, manifestName)), manifestName);
    } catch (error) {
      if (error.code === "ENOENT") return null;
      throw error;
    }
  }

  async function readFileUnder(root, relativePath) {
    const safePath = assertSafeRelativePath(relativePath);
    const absoluteRoot = path.resolve(root);
    const absolutePath = path.resolve(absoluteRoot, ...safePath.split("/"));
    if (!absolutePath.startsWith(`${absoluteRoot}${path.sep}`)) {
      throw new Error(`CoA archive path escapes its cache directory: ${relativePath}`);
    }
    return fs.readFile(absolutePath);
  }

  async function verifyFile(root, fileRecord) {
    const bytes = await readFileUnder(root, fileRecord.path);
    if (bytes.byteLength !== fileRecord.size) throw new Error(`CoA supplement size mismatch for ${fileRecord.path}`);
    if (gitBlobSha(bytes) !== fileRecord.gitBlobSha.toLowerCase()) {
      throw new Error(`CoA supplement Git blob checksum mismatch for ${fileRecord.path}`);
    }
    const actualSha256 = sha256(bytes);
    if (actualSha256 !== fileRecord.sha256.toLowerCase()) {
      throw new Error(`CoA supplement SHA-256 mismatch for ${fileRecord.path}`);
    }
    if (fileRecord.path === archive.fetchManifestPath) parseCaptureManifest(bytes);
    if (fileRecord.path === archive.builderSnapshotPath && actualSha256 !== archive.builderSnapshotSha256) {
      throw new Error(`CoA builder snapshot does not match pinned SHA-256 ${archive.builderSnapshotSha256}`);
    }
    return bytes;
  }

  async function loadPublishedCache(archiveRoot) {
    const manifest = await readManifest(archiveRoot);
    if (manifest === null) return null;
    const expected = expectedFilesFromManifest(manifest);
    const generationRoot = path.join(archiveRoot, manifest.generation);
    const contents = new Map();
    for (const [filePath, record] of expected) contents.set(filePath, await verifyFile(generationRoot, record));
    parseCaptureManifest(contents.get(archive.fetchManifestPath));

    const indexPath = "data/talents/coa/index.json";
    const index = parseJson(contents.get(indexPath), indexPath);
    const classPaths = classPathsFromIndex(index);
    const recordedClassPaths = [...expected.keys()]
      .filter(isClassArchivePath)
      .sort();
    if (classPaths.slice().sort().join("\n") !== recordedClassPaths.join("\n")) {
      throw new Error("CoA supplement manifest class files do not match data/talents/coa/index.json");
    }

    const metadata = {
      talents: parseJson(contents.get("data/talents/coa/_meta.json"), "data/talents/coa/_meta.json"),
      provenance: parseJson(contents.get("raw/provenance.json"), "raw/provenance.json"),
      clientSnapshot: parseJson(contents.get("raw/_snapshot.json"), "raw/_snapshot.json"),
      spells: parseJson(contents.get("data/spells/_meta.json"), "data/spells/_meta.json"),
    };
    const descriptors = descriptorsFromIndex(index);
    const rawClasses = classPaths.map((filePath) => parseJson(contents.get(filePath), filePath));
    const hasTextReferences = rawClasses.some((definition) => definition.nodes?.some((node) => (
      /^\$[0-9a-f]+$/i.test(node.description ?? "")
      || node.rankDescriptions?.some((rank) => /^\$[0-9a-f]+$/i.test(rank.description ?? ""))
    )));
    const classes = hasTextReferences
      ? resolveArchiveDescriptions(rawClasses, contents.get(archive.builderSnapshotPath).toString("utf8"))
      : rawClasses;
    const classFiles = classPaths.map((filePath, position) => ({ path: filePath, indexEntry: descriptors[position], data: classes[position] }));
    return {
      source: structuredClone(manifest.source),
      classes,
      classFiles,
      metadata,
      index,
      manifest: structuredClone(manifest),
    };
  }

  async function atomicWrite(filePath, bytes) {
    await fs.mkdir(path.dirname(filePath), { recursive: true });
    const temporaryPath = `${filePath}.tmp-${randomUUID()}`;
    try {
      await fs.writeFile(temporaryPath, bytes, { flag: "wx" });
      await fs.rename(temporaryPath, filePath);
    } catch (error) {
      await fs.rm(temporaryPath, { force: true }).catch(() => {});
      throw error;
    }
  }

  async function discardInvalidFile(filePath) {
    try {
      await fs.rm(filePath, { force: true });
    } catch (error) {
      throw new Error(`Could not discard invalid cached CoA supplement ${filePath}: ${error.message}`, { cause: error });
    }
  }

  async function readAndVerifyStaged(stagingRoot, expected) {
    let bytes;
    try {
      bytes = await readFileUnder(stagingRoot, expected.path);
    } catch (error) {
      if (error.code === "ENOENT") return null;
      throw error;
    }
    const stagedPath = path.join(stagingRoot, ...expected.path.split("/"));
    if (bytes.byteLength !== expected.size || gitBlobSha(bytes) !== expected.gitBlobSha) {
      await discardInvalidFile(stagedPath);
      return null;
    }
    const contentSha256 = sha256(bytes);
    if (expected.path === archive.fetchManifestPath) {
      try {
        parseCaptureManifest(bytes);
      } catch {
        await discardInvalidFile(stagedPath);
        return null;
      }
    }
    if (expected.path === archive.builderSnapshotPath && contentSha256 !== archive.builderSnapshotSha256) {
      await discardInvalidFile(stagedPath);
      return null;
    }
    return { path: expected.path, gitBlobSha: expected.gitBlobSha, sha256: contentSha256, size: bytes.byteLength };
  }

  async function fetchAndPromoteFile(fetchImpl, stagingRoot, expected) {
    const { rawUrl } = archiveUrls(expected.path);
    const bytes = await responseBytes(fetchImpl, rawUrl, "application/octet-stream");
    if (gitBlobSha(bytes) !== expected.gitBlobSha) {
      throw new Error(`Downloaded CoA supplement Git blob checksum mismatch for ${expected.path}`);
    }
    const contentSha256 = sha256(bytes);
    if (expected.path === archive.fetchManifestPath) parseCaptureManifest(bytes);
    if (expected.path === archive.builderSnapshotPath && contentSha256 !== archive.builderSnapshotSha256) {
      throw new Error(`Downloaded CoA builder snapshot SHA-256 mismatch for ${expected.path}`);
    }
    const record = { path: expected.path, gitBlobSha: expected.gitBlobSha, sha256: contentSha256, size: bytes.byteLength };
    const stagedPath = path.join(stagingRoot, ...expected.path.split("/"));
    await atomicWrite(stagedPath, bytes);
    await verifyFile(stagingRoot, record);
    return record;
  }

  async function stageFile(fetchImpl, stagingRoot, expected) {
    const cached = await readAndVerifyStaged(stagingRoot, expected);
    if (cached) return { record: cached, downloaded: false };
    return { record: await fetchAndPromoteFile(fetchImpl, stagingRoot, expected), downloaded: true };
  }

  async function validateGeneration(generationRoot, manifest) {
    const expected = expectedFilesFromManifest(manifest);
    const contents = new Map();
    for (const [filePath, record] of expected) contents.set(filePath, await verifyFile(generationRoot, record));
    const index = parseJson(contents.get("data/talents/coa/index.json"), "data/talents/coa/index.json");
    const indexedClassPaths = classPathsFromIndex(index).sort();
    const recordedClassPaths = [...expected.keys()]
      .filter(isClassArchivePath)
      .sort();
    if (indexedClassPaths.join("\n") !== recordedClassPaths.join("\n")) {
      throw new Error("CoA supplement generation class files do not match the pinned index");
    }
    parseCaptureManifest(contents.get(archive.fetchManifestPath));
    for (const filePath of [
      "data/talents/coa/_meta.json",
      "raw/provenance.json",
      "raw/_snapshot.json",
      "data/spells/_meta.json",
      ...indexedClassPaths,
    ]) {
      parseJson(contents.get(filePath), filePath);
    }
  }

  async function writeManifest(archiveRoot, manifest) {
    await atomicWrite(
      path.join(archiveRoot, manifestName),
      Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"),
    );
  }

  function cacheSummary(manifest, cacheDirectory, reused, downloadedFiles = []) {
    return {
      source: structuredClone(manifest.source),
      cacheDirectory,
      revision: archive.revision,
      capturedAt: archive.capturedAt,
      fileCount: manifest.files.length,
      classCount: expectedClassCount,
      reused,
      downloadedFiles,
    };
  }

  async function readSupplements({ cacheRoot } = {}) {
    const archiveRoot = archiveDirectory(cacheRoot);
    try {
      await fs.access(archiveRoot);
    } catch (error) {
      if (error.code === "ENOENT") return null;
      throw error;
    }
    try {
      const contents = await loadPublishedCache(archiveRoot);
      if (contents === null) throw new Error("published manifest is missing");
      return contents;
    } catch (error) {
      throw new Error(`CoA supplement cache at ${archiveRoot} is corrupt or incomplete: ${error.message}`, { cause: error });
    }
  }

  async function downloadSupplements({ cacheRoot, fetchImpl = globalThis.fetch, refresh = false } = {}) {
    if (typeof fetchImpl !== "function") throw new TypeError("fetchImpl must be a fetch-compatible function");
    const archiveRoot = archiveDirectory(cacheRoot);
    if (!refresh) {
      try {
        const cached = await loadPublishedCache(archiveRoot);
        if (cached) return cacheSummary(cached.manifest, archiveRoot, true);
      } catch {
        // Keep the previous manifest and generation until a complete replacement is ready.
      }
    }

    await fs.mkdir(archiveRoot, { recursive: true });
    const tree = await fetchTree(fetchImpl);
    const expected = new Map(requiredPaths.map((filePath) => [filePath, expectedFile(tree, filePath)]));
    const stagingRoot = path.join(archiveRoot, "staging");
    const stagedRecords = new Map();
    const downloadedFiles = [];

    for (const filePath of requiredPaths) {
      const staged = await stageFile(fetchImpl, stagingRoot, expected.get(filePath));
      stagedRecords.set(filePath, staged.record);
      if (staged.downloaded) downloadedFiles.push(filePath);
    }

    const indexPath = "data/talents/coa/index.json";
    const index = parseJson(await readFileUnder(stagingRoot, indexPath), indexPath);
    const classPaths = classPathsFromIndex(index);
    for (const filePath of classPaths) expected.set(filePath, expectedFile(tree, filePath));
    for (const filePath of classPaths) {
      const staged = await stageFile(fetchImpl, stagingRoot, expected.get(filePath));
      stagedRecords.set(filePath, staged.record);
      if (staged.downloaded) downloadedFiles.push(filePath);
    }

    const files = [...stagedRecords.values()].sort((left, right) => left.path.localeCompare(right.path));
    if (files.length !== requiredPaths.length + expectedClassCount) {
      throw new Error(`CoA supplemental cache expected ${requiredPaths.length + expectedClassCount} files but staged ${files.length}`);
    }
    parseCaptureManifest(await readFileUnder(stagingRoot, archive.fetchManifestPath));
    const manifest = {
      schemaVersion: cacheSchemaVersion,
      source: sourceRecord(),
      generation: `generation-${randomUUID()}`,
      files,
    };
    // Validate every staged byte before moving the resumable cache into an immutable generation.
    await validateGeneration(stagingRoot, manifest);
    const generationRoot = path.join(archiveRoot, manifest.generation);
    await fs.rename(stagingRoot, generationRoot);
    await writeManifest(archiveRoot, manifest);
    return cacheSummary(manifest, archiveRoot, false, downloadedFiles);
  }

  return Object.freeze({ readSupplements, downloadSupplements });
}

const defaultApi = createSupplementCacheApi();

export const readSupplements = defaultApi.readSupplements;
export const downloadSupplements = defaultApi.downloadSupplements;

export function getDefaultSupplementCacheRoot(projectRoot = defaultProjectRoot) {
  return path.join(path.resolve(projectRoot), "data", "coa-reference", "cache");
}