// Where a Servarr app reaches its download clients and its indexer proxy — decided by the mesh,
// written into the app by the app's own API.
//
// **One file, four copies.** sonarr, radarr, lidarr and bookshelf (a Readarr fork) keep their
// download clients and indexers behind the same API — `/api/v3/…` for the first two, `/api/v1/…`
// for the others — so this step is the same code in each. Each module builds from its own
// directory (novox/hq ADR 0069), so each carries a byte-identical copy under `downloads/`;
// `test/downloads.test.ts` checks the copies agree wherever the siblings are checked out beside
// it. Change all four together.
//
// **Why this exists.** The app keeps its connection to nzbget, qBittorrent and jackett in its own
// database, not in a file, so the mesh has nowhere to write `${bound:nzbget-api:at}` for it. The
// module requires `nzbget-api`, `qbittorrent-api` and `jackett-api`; the mesh delivers, for each,
// a binding (where the provider is — `at` — and what it serves: `port`, `scheme`, `url-base`, and
// for a download client the `username`) and a pair credential (nzbget's ControlPassword,
// qBittorrent's WebUI password, jackett's API key — each the provider's one and only, accepted by
// the operator per pair; the mesh cannot mint them). This step reads those files and makes the
// app's entries say the same thing.
//
// **Which entries are the mesh's.** Never a guess from what an entry looks like:
//   - a download client is the mesh's when its name is the one the module's settings give for
//     that provision (`downloads.<provision>.name`) and its kind is that provider's. On a fresh
//     machine the step registers it under that name; on a migrated one the assignment names the
//     entry the migration adopts ("NZBGet" on ace).
//   - a Torznab indexer is the mesh's when it reads a jackett feed
//     (`…/api/v2.0/indexers/<id>/results/torznab`) on a host the mesh put there — the bound `at`,
//     one it bound before (remembered by the step), or one the settings adopt
//     (`downloads.jackett-api.adopt-hosts`, which is how a migration names the entries that pointed
//     at the old container). `downloads.jackett-api.indexers` lists the jackett indexers the app
//     should have; one missing is registered.
// Everything else — every entry a person made, an nzbget elsewhere, a seedbox's jackett, a Newznab
// indexer — is left exactly as it is. **Nothing is ever deleted.**
//
// **Only the connection, and only when it differs.** Host, port, TLS, base path, user name and
// the credential. Categories, priorities, "enabled", seed criteria and every other choice made in
// the app are left alone. The stored credential cannot be read back (the app masks it), so the
// step asks the app to test the entry with the mesh's host and port and the credential it already
// holds: passing, the credential is already the provider's one and only; failing, the delivered
// credential is written.
//
// **A credential the provider refuses is never written.** Until the operator accepts the
// provider's secret for this pair, the mesh delivers a value it minted itself, which no provider
// will ever accept (novox/hq ADR 0092). Writing it would replace a working password with a dead
// one. So it is tried against the provider first; refused, nothing of that provision is written
// and the step fails naming the `secret accept` that fixes it.
//
// Pure logic and a small HTTP seam, so it is tested against fake servers (test/downloads.test.ts).
// Never prints a credential, an API key, or a URL carrying one.

import { readFile } from "node:fs/promises";

/** A download-client provision and the shape of its entry in the app. */
export interface ClientKind {
  provision: "nzbget-api" | "qbittorrent-api";
  /** The app's `implementation` for it. */
  implementation: "Nzbget" | "QBittorrent";
  /** The provider, as a person calls it. */
  provider: string;
  /** What the pair credential is, in the provider's words. */
  secretName: string;
}

export const CLIENTS: readonly ClientKind[] = [
  { provision: "nzbget-api", implementation: "Nzbget", provider: "nzbget", secretName: "ControlPassword" },
  { provision: "qbittorrent-api", implementation: "QBittorrent", provider: "qBittorrent", secretName: "WebUI password" },
];

export const JACKETT = "jackett-api";

/** What the mesh wrote at `binds.<provision>`: the binding document. */
export interface Binding {
  provision?: string;
  from?: string;
  at?: string;
  as?: string;
  serves?: Record<string, unknown>;
}

/** Where a provider is, as the mesh bound it, and the credential for it. */
export interface Endpoint {
  scheme: "http" | "https";
  host: string;
  port: number;
  /** "" at the root, otherwise "/base" — one leading slash, none trailing. */
  urlBase: string;
  /** The user a download client logs in as; "" for jackett, which takes a key. */
  username: string;
  credential: string;
  /** The provider's node, for the `secret accept` remedy. */
  from: string;
}

export type Wanted = { ok: true; endpoint: Endpoint } | { ok: false; problem: string };

/**
 * The endpoint the mesh says to use, from a binding and its pair credential.
 *
 * Refused rather than guessed when the binding cannot be dialled from the app's own container: a
 * loopback `at` — what the mesh hands a machine that is not on the private network — is the app's
 * container itself.
 */
export function wanted(
  provision: string,
  binding: Binding | undefined,
  credential: string | undefined,
  needsUser: boolean,
): Wanted {
  if (!binding) {
    return { ok: false, problem: `no binding for ${provision} was delivered — the mesh writes it before this step runs` };
  }
  const host = typeof binding.at === "string" ? binding.at.trim() : "";
  const serves = binding.serves ?? {};
  const port = Number(serves.port);
  if (!host) return { ok: false, problem: `the ${provision} binding names no host (at)` };
  if (isLoopback(host)) {
    return {
      ok: false,
      problem:
        `the ${provision} binding says the provider is at ${host}, which from the app's own container is the ` +
        `app itself. The mesh hands loopback to a machine that is not on the private network; put it on the ` +
        `private network so the provider has an address the app can dial`,
    };
  }
  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
    return { ok: false, problem: `the ${provision} binding serves no usable port (${String(serves.port)})` };
  }
  const scheme = typeof serves.scheme === "string" && serves.scheme ? serves.scheme : "http";
  if (scheme !== "http" && scheme !== "https") {
    return { ok: false, problem: `the ${provision} binding serves scheme ${scheme}, which the app cannot dial` };
  }
  const username = typeof serves.username === "string" ? serves.username.trim() : "";
  if (needsUser && !username) {
    return { ok: false, problem: `the ${provision} binding serves no username for the app to log in as` };
  }
  const key = (credential ?? "").trim();
  if (!key) return { ok: false, problem: `the ${provision} credential is empty or was not delivered` };
  return {
    ok: true,
    endpoint: {
      scheme,
      host,
      port,
      urlBase: normBase(serves["url-base"]),
      username,
      credential: key,
      from: typeof binding.from === "string" ? binding.from : "",
    },
  };
}

/** A URL base as "" or "/x/y": slashes trimmed, one put back in front. */
export function normBase(v: unknown): string {
  const s = typeof v === "string" ? v.trim().replace(/^\/+|\/+$/g, "") : "";
  return s === "" ? "" : `/${s}`;
}

function isLoopback(host: string): boolean {
  const h = host.toLowerCase();
  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
}

function hostForUrl(host: string): string {
  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
}

/** The provider's base URL, as the step dials it and as the app is given it. */
export function baseUrl(ep: Endpoint): string {
  return `${ep.scheme}://${hostForUrl(ep.host)}:${ep.port}${ep.urlBase}`;
}

// ---------------------------------------------------------------------------------------------
// HTTP

/** The HTTP the step needs, so a test can stand fakes in for the app and the providers. */
export interface Http {
  fetch(
    url: string,
    init?: { method?: string; headers?: Record<string, string>; body?: string },
  ): Promise<{ status: number; text(): Promise<string> }>;
}

/** The app, as the step reaches it from the host. */
export interface App {
  /** The module, for messages and the remedy: sonarr, radarr, lidarr, bookshelf. */
  module: string;
  /** Its own URL, base path included. */
  url: string;
  apiKey: string;
  /** v3 (sonarr, radarr) or v1 (lidarr, bookshelf). */
  api: string;
}

interface Answer {
  status: number;
  body: unknown;
}

async function appCall(http: Http, app: App, method: string, path: string, body?: unknown): Promise<Answer> {
  const res = await http.fetch(`${app.url.replace(/\/$/, "")}/api/${app.api}${path}`, {
    method,
    headers: {
      "X-Api-Key": app.apiKey,
      Accept: "application/json",
      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
  });
  const text = await res.text();
  let parsed: unknown = undefined;
  if (text) {
    try {
      parsed = JSON.parse(text) as unknown;
    } catch {
      parsed = text;
    }
  }
  return { status: res.status, body: parsed };
}

async function appGet(http: Http, app: App, path: string): Promise<unknown> {
  const a = await appCall(http, app, "GET", path);
  if (a.status < 200 || a.status >= 300) throw new Error(`${app.module} GET ${path} answered ${a.status}`);
  return a.body;
}

/** One of the app's validation failures: the only parts of an answer the step ever prints. */
interface Failure {
  property: string;
  message: string;
  warning: boolean;
}

function failuresOf(body: unknown): Failure[] {
  const list = Array.isArray(body) ? body : [];
  return list.map((f) => {
    const o = (f ?? {}) as Record<string, unknown>;
    return {
      property: String(o.propertyName ?? ""),
      message: String(o.errorMessage ?? ""),
      warning: o.isWarning === true,
    };
  });
}

/**
 * One shape rather than a union on `ok`: the Dockerfile compiles without strict, where a boolean
 * discriminant does not narrow.
 */
interface Verdict {
  ok: boolean;
  /** Warnings the app raised on a pass; errors (and any warnings) on a failure. */
  failures: Failure[];
  status: number;
  saved?: Entry;
}

function verdict(a: Answer): Verdict {
  if (a.status >= 200 && a.status < 300) return { ok: true, failures: [], status: a.status };
  const failures = failuresOf(a.body);
  if (a.status === 400 && failures.length > 0 && failures.every((f) => f.warning)) return { ok: true, failures, status: a.status };
  return { ok: false, failures, status: a.status };
}

/** The app's own test of an entry, from the app's own container. */
async function appTest(http: Http, app: App, resource: string, entry: Entry): Promise<Verdict> {
  return verdict(await appCall(http, app, "POST", `/${resource}/test`, entry));
}

/**
 * Save an entry. The app tests an enabled entry before saving it; a test that passes with only
 * warnings ("a category is recommended") is saved with `forceSave`, the same as pressing "save
 * anyway" in its screen. An error is never forced.
 */
async function appSave(http: Http, app: App, resource: string, entry: Entry, create: boolean): Promise<Verdict> {
  const path = create ? `/${resource}` : `/${resource}/${entry.id}`;
  const method = create ? "POST" : "PUT";
  let a = await appCall(http, app, method, path, entry);
  let v = verdict(a);
  if (v.ok && (a.status < 200 || a.status >= 300)) {
    a = await appCall(http, app, method, `${path}?forceSave=true`, entry);
    v = verdict(a);
    if (v.ok && (a.status < 200 || a.status >= 300)) {
      return { ok: false, failures: failuresOf(a.body), status: a.status };
    }
  }
  if (!v.ok) return v;
  return { ...v, saved: (a.body ?? undefined) as Entry | undefined };
}

// ---------------------------------------------------------------------------------------------
// Entries

/** An entry as the app's API gives it: a download client or an indexer. */
export interface Entry {
  id?: number;
  name?: string;
  implementation?: string;
  enable?: boolean;
  enableRss?: boolean;
  enableAutomaticSearch?: boolean;
  enableInteractiveSearch?: boolean;
  supportsRss?: boolean;
  supportsSearch?: boolean;
  fields?: { name: string; value?: unknown; [k: string]: unknown }[];
  [k: string]: unknown;
}

export function field(e: Entry, name: string): unknown {
  return e.fields?.find((f) => f.name === name)?.value;
}

/** The entry with these fields' values replaced — added when the app's shape lacks one. */
export function withFields(e: Entry, values: Record<string, unknown>): Entry {
  const fields = (e.fields ?? []).map((f) => (f.name in values ? { ...f, value: values[f.name] } : { ...f }));
  for (const [name, value] of Object.entries(values)) {
    if (!fields.some((f) => f.name === name)) fields.push({ name, value });
  }
  return { ...e, fields };
}

function enabled(e: Entry): boolean {
  return e.enable === true || e.enableRss === true || e.enableAutomaticSearch === true || e.enableInteractiveSearch === true;
}

/** What one provision, or one entry of it, came to. */
export type Outcome =
  | { what: string; result: "unchanged"; untested?: boolean }
  | { what: string; result: "written"; fields: string[]; untested?: boolean }
  | { what: string; result: "created"; fields: string[] }
  | { what: string; result: "notice"; note: string }
  | { what: string; result: "refused"; problem: string };

function said(fs: Failure[]): string {
  return fs.length === 0 ? "no reason given" : fs.map((f) => (f.property ? `${f.property}: ${f.message}` : f.message)).join("; ");
}

/**
 * Bring one of the mesh's entries in line: `connection` is the non-secret fields as the mesh says
 * them, `differs` which of them the entry does not already say, `secretField` where the credential
 * goes. Never throws: every failure is an outcome with a reason.
 */
export async function reconcileEntry(
  http: Http,
  app: App,
  resource: "downloadclient" | "indexer",
  what: string,
  current: Entry,
  connection: Record<string, unknown>,
  differs: string[],
  secretField: string,
  credential: string,
  testable = true,
): Promise<Outcome> {
  try {
    const base = withFields(current, connection); // the credential as the app holds it — masked
    if (!testable) {
      // Nothing to test against (jackett no longer has the indexer it names): the connection is
      // still the mesh's to state, and the key goes with it when the address changes.
      if (differs.length === 0) return { what, result: "unchanged", untested: true };
      const s = await appSave(http, app, resource, withFields(base, { [secretField]: credential }), false);
      if (!s.ok) return { what, result: "refused", problem: `${app.module} would not save it: ${said(s.failures)}` };
      return { what, result: "written", fields: [...differs, secretField], untested: true };
    }
    const first = await appTest(http, app, resource, base);
    if (first.ok) {
      // The credential the app holds already works against the provider at the mesh's address —
      // and the provider has exactly one, so it is the delivered one.
      if (differs.length === 0) return { what, result: "unchanged" };
      const s = await appSave(http, app, resource, base, false);
      if (!s.ok) return { what, result: "refused", problem: `${app.module} would not save it: ${said(s.failures)}` };
      return { what, result: "written", fields: differs };
    }
    // The app's test failed with what it holds. The delivered credential was already checked
    // against the provider, so writing it is safe; the app tests an enabled entry again on save.
    const s = await appSave(http, app, resource, withFields(base, { [secretField]: credential }), false);
    if (!s.ok) {
      return {
        what,
        result: "refused",
        problem: `${app.module} tested it at the mesh's address and would not save it (nothing was written): ${said(s.failures)}`,
      };
    }
    const stored = (await appGet(http, app, `/${resource}/${current.id}`)) as Entry;
    const second = await appTest(http, app, resource, stored);
    const fields = [...differs, secretField];
    if (second.ok) return { what, result: "written", fields };
    const why = `written (${fields.join(", ")}), and ${app.module}'s own test still fails: ${said(second.failures)}`;
    return enabled(stored) ? { what, result: "refused", problem: why } : { what, result: "notice", note: `${why} — it is disabled, so nothing uses it` };
  } catch (err) {
    return { what, result: "refused", problem: message(err) };
  }
}

/**
 * Register a new entry from the app's own template for that kind: its defaults, the name, the
 * connection and the credential. A category the provider does not have (nzbget refuses one it was
 * not told about) is left empty rather than failing the registration, and said.
 */
export async function createEntry(
  http: Http,
  app: App,
  resource: "downloadclient" | "indexer",
  what: string,
  implementation: string,
  name: string,
  values: Record<string, unknown>,
): Promise<Outcome> {
  try {
    const schema = (await appGet(http, app, `/${resource}/schema`)) as Entry[];
    const template = (schema ?? []).find((s) => s.implementation === implementation);
    if (!template) return { what, result: "refused", problem: `${app.module} has no ${implementation} to register` };
    let entry: Entry = withFields({ ...template, id: undefined, name }, values);
    if (resource === "downloadclient") entry.enable = true;
    else {
      entry.enableRss = template.supportsRss !== false;
      entry.enableAutomaticSearch = template.supportsSearch !== false;
      entry.enableInteractiveSearch = template.supportsSearch !== false;
    }
    let s = await appSave(http, app, resource, entry, true);
    let note = "";
    if (!s.ok && s.failures.length > 0 && s.failures.every((f) => /category/i.test(f.property))) {
      const emptied: Record<string, unknown> = {};
      for (const f of entry.fields ?? []) if (/category$/i.test(f.name) && !/imported/i.test(f.name)) emptied[f.name] = "";
      entry = withFields(entry, emptied);
      s = await appSave(http, app, resource, entry, true);
      note = " with its category left empty — the provider has none by the app's default name; set one in both";
    }
    if (!s.ok) return { what, result: "refused", problem: `${app.module} would not register it: ${said(s.failures)}` };
    const created = s.saved;
    if (created?.id !== undefined) {
      const t = await appTest(http, app, resource, (await appGet(http, app, `/${resource}/${created.id}`)) as Entry);
      if (!t.ok) {
        return { what, result: "refused", problem: `registered as "${name}"${note}, and ${app.module}'s own test fails: ${said(t.failures)}` };
      }
    }
    return note
      ? { what, result: "notice", note: `registered as "${name}"${note}` }
      : { what, result: "created", fields: Object.keys(values) };
  } catch (err) {
    return { what, result: "refused", problem: message(err) };
  }
}

// ---------------------------------------------------------------------------------------------
// Providers: does it take the credential?

/**
 * Does the provider take this credential? `took` it does (for jackett, with the ids of the indexers
 * it has configured); `refused` it said no; a thrown error when it could not be asked.
 */
export interface Took {
  took: boolean;
  configured?: Map<string, string>;
}

export async function providerTakes(http: Http, provision: string, ep: Endpoint): Promise<Took> {
  const base = baseUrl(ep);
  if (provision === "nzbget-api") {
    const auth = Buffer.from(`${ep.username}:${ep.credential}`).toString("base64");
    const res = await http.fetch(`${base}/jsonrpc/version`, { method: "GET", headers: { Authorization: `Basic ${auth}` } });
    await res.text();
    if (res.status === 401 || res.status === 403) return { took: false };
    if (res.status >= 200 && res.status < 300) return { took: true };
    throw new Error(`nzbget answered ${res.status}`);
  }
  if (provision === "qbittorrent-api") {
    const form = `username=${encodeURIComponent(ep.username)}&password=${encodeURIComponent(ep.credential)}`;
    const res = await http.fetch(`${base}/api/v2/auth/login`, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: form,
    });
    const text = (await res.text()).trim();
    if (res.status === 401 || /^fails\.?$/i.test(text)) return { took: false };
    if (res.status === 403) {
      throw new Error(
        "qBittorrent answered 403: it has banned this address after failed logins (WebUI\\BanDuration); it lifts by itself",
      );
    }
    if (res.status >= 200 && res.status < 300) return { took: true };
    throw new Error(`qBittorrent answered ${res.status}`);
  }
  if (provision === JACKETT) {
    const url = `${base}/api/v2.0/indexers/all/results/torznab/api?t=indexers&configured=true&apikey=${encodeURIComponent(ep.credential)}`;
    const res = await http.fetch(url, { method: "GET" });
    const text = await res.text();
    if (res.status === 401 || res.status === 403) return { took: false };
    if (res.status < 200 || res.status >= 300) throw new Error(`jackett answered ${res.status}`);
    // jackett answers a wrong key 200 with an error document: code 100, "Invalid API Key".
    if (/<error\b[^>]*\bcode="100"/i.test(text)) return { took: false };
    if (/<error\b/i.test(text)) throw new Error("jackett answered with an error document");
    return { took: true, configured: configuredIndexers(text) };
  }
  throw new Error(`no check for ${provision}`);
}

/** jackett's configured indexers, id → title, from its `t=indexers` feed. */
export function configuredIndexers(xml: string): Map<string, string> {
  const out = new Map<string, string>();
  const re = /<indexer\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/indexer>/g;
  for (let m = re.exec(xml); m; m = re.exec(xml)) {
    const title = /<title>([\s\S]*?)<\/title>/.exec(m[2])?.[1]?.trim() ?? m[1];
    out.set(m[1], decodeXml(title));
  }
  return out;
}

function decodeXml(s: string): string {
  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
}

/** The remedy for a refused credential, in the controller's own words (ADR 0092). */
export function acceptRemedy(app: App, node: string, provision: string, provider: string, secretName: string, from: string): string {
  return (
    `${provider} refuses the ${provision} credential the mesh delivered, so nothing of ${provision} was written ` +
    `into ${app.module}. ${provider} has one ${secretName} and the mesh cannot make it: accept it for this pair — ` +
    `\`secret accept ${node || "<this node>"} ${app.module} ${provision} --provider ${from || "<its node>"} ` +
    `--from <file holding ${provider}'s ${secretName}>\``
  );
}

// ---------------------------------------------------------------------------------------------
// Download clients

/** The non-secret fields of a download client as the mesh says them. */
export function clientConnection(ep: Endpoint): Record<string, unknown> {
  return { host: ep.host, port: ep.port, useSsl: ep.scheme === "https", urlBase: ep.urlBase === "" ? null : ep.urlBase, username: ep.username };
}

/** Which of them the entry does not already say. Names only. */
export function clientDiffers(e: Entry, ep: Endpoint): string[] {
  const out: string[] = [];
  if (String(field(e, "host") ?? "").toLowerCase() !== ep.host.toLowerCase()) out.push("host");
  if (Number(field(e, "port") ?? 0) !== ep.port) out.push("port");
  if (Boolean(field(e, "useSsl")) !== (ep.scheme === "https")) out.push("useSsl");
  if (normBase(field(e, "urlBase")) !== ep.urlBase) out.push("urlBase");
  if (String(field(e, "username") ?? "") !== ep.username) out.push("username");
  return out;
}

/**
 * Bring the app's download client for one provision in line: the entry by that name and kind is
 * the mesh's and is updated; none, it is registered. An entry by that name of another kind, or by
 * that name in another case, is somebody else's and is refused rather than touched.
 */
export async function reconcileClient(
  http: Http,
  app: App,
  kind: ClientKind,
  name: string,
  ep: Endpoint,
  entries: Entry[],
): Promise<Outcome[]> {
  const what = `${kind.provision} ("${name}")`;
  const exact = entries.filter((e) => e.name === name);
  const alike = entries.filter((e) => e.name !== name && String(e.name ?? "").toLowerCase() === name.toLowerCase());
  if (exact.length > 0 && exact[0].implementation !== kind.implementation) {
    return [{
      what,
      result: "refused",
      problem: `the download client named "${name}" is a ${exact[0].implementation}, not ${kind.implementation}; it is not the mesh's and was left alone. Name the mesh's entry otherwise in downloads.${kind.provision}.name`,
    }];
  }
  if (exact.length === 0 && alike.length > 0) {
    return [{
      what,
      result: "refused",
      problem: `${app.module} already has "${alike[0].name}", which is not the mesh's name ("${name}") and was left alone. To have the mesh manage it, set downloads.${kind.provision}.name to "${alike[0].name}"`,
    }];
  }
  const outcomes: Outcome[] = [];
  const others = entries.filter((e) => e.implementation === kind.implementation && e.name !== name);
  if (others.length > 0) {
    outcomes.push({
      what,
      result: "notice",
      note: `also present and not the mesh's, left alone: ${others.map((o) => `"${o.name}"`).join(", ")}`,
    });
  }
  if (exact.length === 0) {
    outcomes.push(
      await createEntry(http, app, "downloadclient", what, kind.implementation, name, {
        ...clientConnection(ep),
        password: ep.credential,
      }),
    );
    return outcomes;
  }
  outcomes.push(
    await reconcileEntry(http, app, "downloadclient", what, exact[0], clientConnection(ep), clientDiffers(exact[0], ep), "password", ep.credential),
  );
  return outcomes;
}

// ---------------------------------------------------------------------------------------------
// Indexers

const FEED = /\/api\/v2\.0\/indexers\/([^/]+)\/results\/torznab\/?$/;

/** A Torznab entry reading a jackett feed: the host it points at and the jackett indexer's id. */
export function jackettFeed(e: Entry): { host: string; id: string } | undefined {
  if (e.implementation !== "Torznab") return undefined;
  const raw = String(field(e, "baseUrl") ?? "").trim();
  if (!raw) return undefined;
  let u: URL;
  try {
    u = new URL(raw);
  } catch {
    return undefined;
  }
  const path = `${u.pathname.replace(/\/+$/, "")}/${String(field(e, "apiPath") ?? "").replace(/^\/+/, "")}`;
  const m = FEED.exec(path);
  if (!m) return undefined;
  return { host: u.hostname.replace(/^\[|\]$/g, "").toLowerCase(), id: decodeURIComponent(m[1]) };
}

/** The feed's two fields as the mesh says them. */
export function feedConnection(ep: Endpoint, id: string): Record<string, unknown> {
  return { baseUrl: baseUrl(ep), apiPath: `/api/v2.0/indexers/${id}/results/torznab/` };
}

function sameUrl(a: string, b: string): boolean {
  try {
    const x = new URL(a);
    const y = new URL(b);
    const port = (u: URL) => u.port || (u.protocol === "https:" ? "443" : "80");
    return (
      x.protocol === y.protocol &&
      x.hostname.toLowerCase() === y.hostname.toLowerCase() &&
      port(x) === port(y) &&
      x.pathname.replace(/\/+$/, "") === y.pathname.replace(/\/+$/, "")
    );
  } catch {
    return false;
  }
}

export function feedDiffers(e: Entry, ep: Endpoint, id: string): string[] {
  const want = feedConnection(ep, id);
  const out: string[] = [];
  if (!sameUrl(String(field(e, "baseUrl") ?? ""), String(want.baseUrl))) out.push("baseUrl");
  const path = (v: unknown) => `/${String(v ?? "").replace(/^\/+|\/+$/g, "")}`;
  if (path(field(e, "apiPath")) !== path(want.apiPath)) out.push("apiPath");
  return out;
}

export interface IndexerSettings {
  /** Hosts whose jackett feeds the mesh takes over — a migration's old names. */
  adoptHosts: string[];
  /** jackett indexer ids the app should have. */
  indexers: string[];
}

/**
 * Bring the app's jackett feeds in line: every one the mesh manages is pointed at the bound jackett
 * with its key, and every listed jackett indexer the app lacks is registered.
 */
export async function reconcileIndexers(
  http: Http,
  app: App,
  ep: Endpoint,
  configured: Map<string, string>,
  settings: IndexerSettings,
  remembered: string[],
  entries: Entry[],
): Promise<Outcome[]> {
  const ours = new Set([ep.host, ...settings.adoptHosts, ...remembered].map((h) => h.trim().toLowerCase()).filter(Boolean));
  const outcomes: Outcome[] = [];
  const managed = new Set<string>();
  for (const e of entries) {
    const feed = jackettFeed(e);
    if (!feed || !ours.has(feed.host)) continue;
    managed.add(feed.id);
    const what = `jackett-api ("${e.name}", jackett indexer ${feed.id})`;
    const known = feed.id === "all" || configured.has(feed.id);
    const outcome = await reconcileEntry(
      http, app, "indexer", what, e, feedConnection(ep, feed.id), feedDiffers(e, ep, feed.id), "apiKey", ep.credential, known,
    );
    outcomes.push(outcome);
    if (!known && outcome.result !== "refused") {
      outcomes.push({ what, result: "notice", note: `jackett has no indexer "${feed.id}" configured, so it was not tested; configure it in jackett or remove the entry in ${app.module}` });
    }
  }
  for (const id of settings.indexers) {
    if (managed.has(id)) continue;
    const what = `jackett-api (jackett indexer ${id})`;
    if (id !== "all" && !configured.has(id)) {
      outcomes.push({ what, result: "refused", problem: `downloads.jackett-api.indexers lists "${id}", and jackett has no indexer by that id configured` });
      continue;
    }
    const name = `Jackett - ${id === "all" ? "all" : configured.get(id)}`;
    outcomes.push(await createEntry(http, app, "indexer", what, "Torznab", name, { ...feedConnection(ep, id), apiKey: ep.credential }));
  }
  if (outcomes.length === 0) {
    outcomes.push({ what: "jackett-api", result: "notice", note: `${app.module} has no jackett feed the mesh manages, and downloads.jackett-api.indexers lists none to register` });
  }
  return outcomes;
}

// ---------------------------------------------------------------------------------------------
// Files

/** The module's settings for this step, from its merged `downloads.json`. */
export interface StepSettings {
  node: string;
  names: Record<string, string>;
  indexers: IndexerSettings;
}

export function stepSettings(raw: unknown): StepSettings {
  const doc = (raw ?? {}) as Record<string, unknown>;
  const d = (doc.downloads ?? {}) as Record<string, Record<string, unknown> | undefined>;
  const names: Record<string, string> = {};
  for (const k of CLIENTS) {
    const n = d[k.provision]?.name;
    names[k.provision] = typeof n === "string" && n.trim() ? n.trim() : k.provision.replace(/-api$/, "");
  }
  const j = d[JACKETT] ?? {};
  const strings = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && x.trim() !== "").map((x) => x.trim()) : []);
  return {
    node: typeof doc.node === "string" ? doc.node : "",
    names,
    indexers: { adoptHosts: strings(j["adopt-hosts"]), indexers: strings(j.indexers) },
  };
}

/** The app's own key and base path, from its config.xml. */
export function appConfig(xml: string): { apiKey: string; urlBase: string } {
  const tag = (t: string) => new RegExp(`<${t}>([^<]*)</${t}>`).exec(xml)?.[1]?.trim() ?? "";
  return { apiKey: tag("ApiKey"), urlBase: normBase(tag("UrlBase")) };
}

/** A file the mesh wrote, or undefined when it is not there. */
export async function readIfThere(path: string | undefined): Promise<string | undefined> {
  if (!path) return undefined;
  return readFile(path, "utf8").catch(() => undefined);
}

/** A JSON file parsed, or undefined when absent or not JSON. */
export async function readJson(path: string | undefined): Promise<unknown> {
  const raw = await readIfThere(path);
  if (raw === undefined) return undefined;
  try {
    return JSON.parse(raw) as unknown;
  } catch {
    return undefined;
  }
}

/** Wait for the app to answer, because the step runs right after its container starts. */
export async function appReady(http: Http, app: App, waitMs: number, pauseMs = 2000): Promise<boolean> {
  const until = Date.now() + waitMs;
  for (;;) {
    try {
      const a = await appCall(http, app, "GET", "/system/status");
      if (a.status === 200) return true;
    } catch {
      // not listening yet
    }
    if (Date.now() >= until) return false;
    await new Promise((r) => setTimeout(r, pauseMs));
  }
}

export async function listEntries(http: Http, app: App, resource: "downloadclient" | "indexer"): Promise<Entry[]> {
  return ((await appGet(http, app, `/${resource}`)) as Entry[]) ?? [];
}

/** Anything printed goes through this: the credentials the step holds never reach a log. */
export function scrub(text: string, secrets: string[]): string {
  let out = text;
  for (const s of secrets) if (s && s.length >= 4) out = out.split(s).join("<redacted>");
  return out;
}

function message(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
}