// `archilyzer source publish` — the repo on the project site, read-only.
//
// The private repository is never rewritten. Every publish makes a FRESH bare
// clone of its `main`, rewrites that copy with git-filter-repo (the operator's
// scrub rules over file contents AND commit messages), repacks it for git's
// dumb-HTTP protocol, and publishes these under homepage/public:
//
//   source/archilyzer.git/   a clonable mirror: HEAD, refs, info/refs,
//                            objects/info/packs, the packs — static files only
//   source/tree/             the tracked files of main, raw, with an
//                            index.html per directory (sourceTree.ts)
//   source/git/              the history: the log, a page per commit with its
//                            diff, the refs, two Atom feeds — stagit's, when
//                            it is installed (sourceHistory.ts)
//   downloads/               archilyzer-source.tar.gz + snapshot.json, the
//                            tarball the Downloads page has always offered
//   source/manifest.json     written LAST: what was published, from what
//
// THE GATE. Before anything is staged for the site, every object of the
// rewritten mirror, and then every staged file, is searched for every denied
// literal (sourceAudit.ts): the operator's denylist plus every scrub rule's
// left side. One hit and nothing is written; the report names the literal by
// number, never by its bytes.
//
// OPERATOR-PRIVATE INPUTS live outside the repo, in
// `${ARCHILYZER_CONFIG_DIR ?? ~/.config/archilyzer}/`: source-scrub.txt
// (git-filter-repo `lhs==>rhs` lines; `<home dir>==>/home/user` is always
// applied first) and source-denylist.txt (one literal per line, `i:` = any
// case). A missing file is a refusal naming it. Nothing here names a user.
//
// `buildHomepage` runs this between compose and `next build`, so `archilyzer
// build homepage`, the runbooks' home scripts and the editor's /sites homepage
// jobs all publish it; an unchanged main with unchanged rules skips.

import { execFile } from "node:child_process";
import { createHash } from "node:crypto";
import { createReadStream, existsSync } from "node:fs";
import { cp, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { runChildIntoLog } from "../jobs/runChild";
import { copyPublicFile, ownDir, writePublicFile } from "../bin/_publicFile";
import { getPaths, type Paths } from "../lib/paths";
import { PROJECT_NAME, PROJECT_URL } from "../lib/project";
import { PUBLISH_MAX_FILE_BYTES } from "../lib/builtExport";
import {
  CLONE_URL,
  HISTORY_DIR,
  HISTORY_LOG_HREF,
  MIRROR_DIR,
  SOURCE_MANIFEST_VERSION,
  TARBALL_HREF,
  TREE_HREF,
  parseSourceManifest,
  type SourceHistory,
  type SourceManifest,
} from "../lib/sourceManifest";
import {
  HistoryProblem,
  STAGIT_INSTALL,
  dropHistoryCache,
  SOURCE_HISTORY_MAX_COMMITS,
  historyCacheKey,
  historyStylesheet,
  homepageThemeScript,
  renderHistory,
  resolveStagit,
  stagitIdentity,
  type HistoryRun,
} from "./sourceHistory";
import {
  SourceRefusal,
  auditBare,
  auditFiles,
  cleanGitEnv,
  dedupeLiterals,
  formatAuditReport,
  operatorLines,
  maskLiterals,
  onPath,
  parseDenylist,
  tildify,
  type Literal,
} from "./sourceAudit";
import { writeTreeIndexes } from "./sourceTree";
// Type-only: build.ts imports THIS module lazily, and must not load it (or the
// AWS SDK this would drag in) at import time.
import type { PublishOpts } from "./build";

export { SourceRefusal } from "./sourceAudit";

/** The one branch mirrored (an operator decision: no other refs, no tags). */
export const SOURCE_BRANCH = "main";

/**
 * The step's own version, hashed into the rules hash (the skip key and the
 * deploy check). BUMP IT WHENEVER THE SCRUB OR THE AUDIT CHANGES — what the
 * rules parse to, what the gate reads, what it refuses — so an unchanged
 * `main` is re-published through the fixed step instead of skipped, and a
 * `homepage/out` built by the old step refuses to deploy.
 *   1 — release 12 slice R.
 *   2 — release 12 slice R review: BOM/CRLF/trailing-slash parsing, empty
 *       left sides refused, `404.html` refused, no context bytes.
 *   3 — the re-review: masked refusal messages, a digest of every published
 *       file and the gitleaks identity in the key.
 *   4 — release 15 slice SG: the history pages (source/git/, stagit) are
 *       staged, swept by the file gate and bound by the digest; stagit's
 *       identity is in the key.
 */
export const SOURCE_STEP_VERSION = 4;

/** What `pipx run` fetches when `git filter-repo` is not installed. */
export const FILTER_REPO_PIPX_SPEC = "git-filter-repo==2.47.0";
export const FILTER_REPO_INSTALL = "pipx install git-filter-repo";

/** The home-directory rule's replacement (always the first scrub rule). */
export const HOME_REPLACEMENT = "/home/user";

// Cloudflare Pages allows 20,000 files per deployment and 25 MiB per file;
// the step refuses well inside both, leaving the rest of the site its room.
export const MAX_FILES = 15_000;
export const MAX_FILE_BYTES = PUBLISH_MAX_FILE_BYTES;

// Packs are split at this size (under the per-file cap, with room to grow).
const PACK_SIZE = "20m";

const TARBALL_NAME = path.basename(TARBALL_HREF);

export type SourcePublishOpts = PublishOpts & {
  // Rebuild even when main and the rules are unchanged.
  force?: boolean;
  // Build, audit and count everything, then write NOTHING.
  check?: boolean;
  // Leave the scratch dir (the rewritten bare clone, the stage) for a look.
  keepScratch?: boolean;
  // The repository to mirror. Default: ARCHILYZER_SOURCE_REPO (a container's
  // mount of the host's repository), else this checkout's git COMMON dir, so a
  // worktree build mirrors the primary's main.
  sourceRepo?: string;
  // Default: HOMEPAGE_PUBLIC_DIR, else <repo>/homepage/public.
  publicDir?: string;
  scrubFile?: string;
  denylistFile?: string;
  // The filter-repo argv; default: resolveFilterRepo().
  filterRepo?: string[] | null;
  // The gitleaks binary; null skips the secret scan (tests). Default "gitleaks".
  gitleaks?: string | null;
  // The stagit binary; null publishes without the history pages, as a
  // machine without stagit does. Default: resolveStagit(paths.stagitBin).
  stagit?: string | null;
  // The history's render cache; null renders without one. Default:
  // paths.sourceHistoryCacheDir (~/.cache/archilyzer/source-history).
  historyCacheDir?: string | null;
  // The history's cap. Default: SOURCE_HISTORY_MAX_COMMITS (the tests' seam).
  maxHistoryCommits?: number;
  // The file limit the history's last-resort drop checks. Default: MAX_FILES
  // (the tests' seam; step 14 always applies MAX_FILES).
  historyFileLimit?: number;
  // The design tokens the history pages' style.css is written from. Default:
  // <repo>/common/styles/tokens.css.
  tokensFile?: string;
  // Where the scratch dir is made. Default: paths.sourceScratchDir.
  scratchRoot?: string;
  // The environment the children run in (PATH decides which tools). Default:
  // process.env.
  env?: NodeJS.ProcessEnv;
  now?: () => Date;
  // The home dir the built-in rule scrubs. Default: os.homedir().
  homeDir?: string;
  // A checkout with no git repository: "refuse" (the CLI: exit 1) or "empty"
  // (buildHomepage: the /source page's empty state, exit 0). Either way it
  // says NO_REPOSITORY and removes an old publish.
  noRepository?: "refuse" | "empty";
};

// ── the operator's files ────────────────────────────────────────────────────

export type ScrubRules = {
  // replace.txt as filter-repo will read it: the built-in rule first, then
  // the operator's rules in order (comments and blank lines dropped —
  // filter-repo itself would treat a `#` line as a literal to replace).
  lines: string[];
  // Every rule's LITERAL left side: denied, exact case, by implication, with
  // where it was written (the report's name for it).
  denied: Array<{ text: string; from: string }>;
};

export const BUILT_IN_HOME_RULE = "built-in home rule";

// CLAUDE SESSION LINKS NEVER SHIP (operator, 2026-10-09). The session trailer
// a coding agent appends to a commit message, or a bare link to a session,
// names a private session of the operator's account. Every published history
// is rewritten without them — the trailer line goes from every commit message
// and every file, a bare link becomes a placeholder — and the audit then
// refuses any that is left. Applied after the operator's rules (filter-repo
// reads both files in order). The strings are assembled from parts so that
// this file, which is published too, holds neither a trailer nor a link.
export const BUILT_IN_SESSION_RULE = "built-in session-link rule";
export const SESSION_TRAILER = ["Claude", "Session"].join("-") + ":";
export const SESSION_LINK_LITERAL = ["claude.ai", "code", "session"].join("/");
export const SESSION_LINK_RULES: readonly string[] = [
  String.raw`regex:\n?[ \t>]*` + SESSION_TRAILER + String.raw`[^\n]*==>`,
  String.raw`regex:https?://` + SESSION_LINK_LITERAL.replace(/\./g, String.raw`\.`) + String.raw`[A-Za-z0-9_/-]*==>[session link removed]`,
];

/**
 * The scrub file's text as rules. A line is `lhs==>rhs` (split at the LAST
 * `==>`, as filter-repo splits it), `literal:lhs==>rhs`, `regex:…==>…` or
 * `glob:…==>…`; a line with no `==>` is replaced by filter-repo's
 * `***REMOVED***`. Lines whose first non-blank character is `#` are comments.
 * A byte-order mark and CRLF endings are dropped first (operatorLines), and
 * the home dir loses a trailing `/`: either would make a rule — and the
 * denial it implies — silently match nothing. An empty left side is a
 * refusal, not a rule filter-repo would skip.
 */
export function parseScrubRules(text: string, homeDir: string): ScrubRules {
  const lines: string[] = [];
  const denied: ScrubRules["denied"] = [];
  const home = homeDir.replace(/\/+$/, "");
  // A home dir of `/` (a container user) would scrub every slash, and one
  // that IS the replacement would deny the replacement itself.
  if (home.length > 1 && home !== HOME_REPLACEMENT) {
    lines.push(`${home}==>${HOME_REPLACEMENT}`);
    denied.push({ text: home, from: BUILT_IN_HOME_RULE });
  }
  operatorLines(text).forEach((line, n) => {
    const t = line.trim();
    if (t === "" || t.startsWith("#")) return;
    const i = line.lastIndexOf("==>");
    let lhs = i === -1 ? line : line.slice(0, i);
    const from = `scrub line ${n + 1} lhs`;
    for (const prefix of ["regex:", "glob:", "literal:"]) {
      if (lhs.startsWith(prefix)) {
        if (lhs.length === prefix.length) {
          throw new SourceRefusal(`scrub line ${n + 1} has an empty left side — it would match nothing and deny nothing`);
        }
        if (prefix === "literal:") lhs = lhs.slice(prefix.length);
        else lhs = "";
        break;
      }
    }
    if (i === 0) {
      throw new SourceRefusal(`scrub line ${n + 1} has an empty left side — it would match nothing and deny nothing`);
    }
    lines.push(line);
    if (lhs) denied.push({ text: lhs, from });
  });
  return { lines, denied };
}

export type SourceRules = {
  scrub: ScrubRules;
  literals: Literal[];
  // Changes whenever a rule or a literal does: part of the skip key. Never
  // published (a hash of the denylist would confirm a guess at it).
  rulesHash: string;
};

async function readOperatorFile(file: string, what: string, how: string): Promise<string> {
  try {
    return await readFile(file, "utf8");
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
      throw new SourceRefusal(`no ${what} at ${tildify(file)} — ${how}`);
    }
    throw err;
  }
}

/** Both operator files, parsed, with the literal list the gate searches for. */
export async function loadSourceRules(opts: {
  scrubFile: string;
  denylistFile: string;
  homeDir?: string;
}): Promise<SourceRules> {
  const scrubText = await readOperatorFile(
    opts.scrubFile,
    "scrub rules",
    "create it (git-filter-repo `lhs==>rhs` lines; the home-directory rule is built in, so it may be empty) or point SOURCE_SCRUB_FILE at one",
  );
  const denyText = await readOperatorFile(
    opts.denylistFile,
    "denylist",
    "create it (one literal per line, `i:` for any case; every scrub rule's left side is denied too, so it may be empty) or point SOURCE_DENYLIST_FILE at one",
  );
  const parsed = parseScrubRules(scrubText, opts.homeDir ?? os.homedir());
  const scrub: ScrubRules = { ...parsed, lines: [...parsed.lines, ...SESSION_LINK_RULES] };
  const literals = dedupeLiterals([
    ...parseDenylist(denyText),
    ...scrub.denied.map((d) => ({ bytes: Buffer.from(d.text, "utf8"), ci: false, from: d.from })),
    { bytes: Buffer.from(SESSION_LINK_LITERAL, "utf8"), ci: true, from: BUILT_IN_SESSION_RULE },
  ]);
  return { scrub, literals, rulesHash: rulesHashOf(scrub.lines, literals, SOURCE_STEP_VERSION) };
}

/**
 * The rules hash: the scrub lines, every literal (and whether it is `i:`),
 * and the step's version — so a fix to the step moves it like a new rule does.
 */
export function rulesHashOf(lines: readonly string[], literals: readonly Literal[], step: number): string {
  return createHash("sha256")
    .update(
      JSON.stringify({
        step,
        rules: lines,
        literals: literals.map((l) => `${l.ci ? "i" : "x"}:${l.bytes.toString("hex")}`),
      }),
    )
    .digest("hex");
}

// ── children ────────────────────────────────────────────────────────────────

type Ctx = {
  onLog: (line: string) => void;
  signal: AbortSignal;
  env: NodeJS.ProcessEnv;
  // Every echoed or quoted child line is masked with these once they are known.
  literals: readonly Literal[];
};

class Cancelled extends Error {}

/**
 * One child through runChildIntoLog, with a timeout. Returns its combined
 * output. A non-zero exit or a timeout is a refusal quoting its last lines
 * (masked); a cancel throws Cancelled.
 */
async function run(
  ctx: Ctx,
  command: string,
  args: string[],
  o: { cwd: string; timeoutMs: number; echo?: boolean; allowFail?: boolean },
): Promise<{ code: number; out: string[] }> {
  const out: string[] = [];
  const timeout = AbortSignal.timeout(o.timeoutMs);
  const code = await runChildIntoLog(
    (line) => {
      out.push(line);
      if (o.echo) ctx.onLog(`[source]   ${maskLiterals(line, ctx.literals)}`);
    },
    AbortSignal.any([ctx.signal, timeout]),
    { command, args, cwd: o.cwd, env: ctx.env },
  );
  if (ctx.signal.aborted) throw new Cancelled();
  // `git --git-dir <path> repack …` is named by its verb, not the path.
  const what = `${command} ${(args[0] === "--git-dir" ? args.slice(2, 3) : args.slice(0, 2)).join(" ")}`;
  if (timeout.aborted) {
    throw new SourceRefusal(`${what} timed out after ${Math.round(o.timeoutMs / 1000)} s`);
  }
  if (code !== 0 && !o.allowFail) {
    const tail = out.slice(-3).map((l) => maskLiterals(l, ctx.literals)).join(" / ");
    throw new SourceRefusal(`${what} exited ${code}${tail ? `: ${tail}` : ""}`);
  }
  return { code, out };
}

const lastLine = (out: string[]) => (out.filter((l) => l.trim()).at(-1) ?? "").trim();
const OID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;

async function revParse(ctx: Ctx, gitDir: string, rev: string): Promise<string> {
  const { out } = await run(ctx, "git", ["--git-dir", gitDir, "rev-parse", "--verify", rev], {
    cwd: gitDir,
    timeoutMs: 30_000,
  });
  const oid = lastLine(out);
  if (!OID.test(oid)) throw new SourceRefusal(`git rev-parse ${rev}: not an object id`);
  return oid;
}

export type FilterRepoChoice = { argv: string[]; label: string; version: string };

/**
 * Which git-filter-repo runs: an installed `git filter-repo`, else `pipx run`
 * of the pinned version (network on first use), else a refusal with the
 * install line.
 */
export async function resolveFilterRepo(opts: {
  env?: NodeJS.ProcessEnv;
  signal?: AbortSignal;
  onLog?: (line: string) => void;
}): Promise<FilterRepoChoice> {
  const ctx: Ctx = {
    onLog: opts.onLog ?? (() => {}),
    signal: opts.signal ?? new AbortController().signal,
    env: cleanGitEnv(opts.env ?? process.env),
    literals: [],
  };
  const cwd = os.tmpdir();
  const installed = await run(ctx, "git", ["filter-repo", "--version"], {
    cwd,
    timeoutMs: 30_000,
    allowFail: true,
  });
  if (installed.code === 0) {
    return { argv: ["git", "filter-repo"], label: "git filter-repo", version: lastLine(installed.out) };
  }
  if (!onPath("pipx", ctx.env.PATH)) {
    throw new SourceRefusal(
      `git-filter-repo is not installed and pipx is not on PATH — install it once: \`${FILTER_REPO_INSTALL}\` (pipx comes from your OS's packages)`,
    );
  }
  const argv = ["pipx", "run", "--spec", FILTER_REPO_PIPX_SPEC, "git-filter-repo"];
  const viaPipx = await run(ctx, argv[0], [...argv.slice(1), "--version"], {
    cwd,
    timeoutMs: 300_000,
    allowFail: true,
  });
  if (viaPipx.code !== 0) {
    throw new SourceRefusal(
      `\`pipx run --spec ${FILTER_REPO_PIPX_SPEC}\` failed (exit ${viaPipx.code}; it needs the network on first use) — install it once: \`${FILTER_REPO_INSTALL}\``,
    );
  }
  return {
    argv,
    label: `pipx run --spec ${FILTER_REPO_PIPX_SPEC} git-filter-repo`,
    version: lastLine(viaPipx.out),
  };
}

// ── helpers ─────────────────────────────────────────────────────────────────

function terminalLog(line: string): void {
  process.stdout.write(line.endsWith("\n") ? line : `${line}\n`);
}

function sha256File(file: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const h = createHash("sha256");
    createReadStream(file)
      .on("data", (c) => h.update(c))
      .on("error", reject)
      .on("end", () => resolve(h.digest("hex")));
  });
}

async function walkFiles(dir: string): Promise<Array<{ rel: string; bytes: number }>> {
  const out: Array<{ rel: string; bytes: number }> = [];
  const walk = async (rel: string) => {
    for (const ent of await readdir(path.join(dir, rel), { withFileTypes: true })) {
      const r = rel ? `${rel}/${ent.name}` : ent.name;
      if (ent.isDirectory()) await walk(r);
      else out.push({ rel: r, bytes: (await stat(path.join(dir, r))).size });
    }
  };
  await walk("");
  return out;
}

const mb = (bytes: number) => (bytes / (1024 * 1024)).toFixed(1);

/**
 * Why `files` may not be published on Pages, as one sentence — or null. The
 * step's limits sit inside the host's: 15,000 files of its 20,000 per
 * deployment (the rest of the site needs room), 24 MiB of its 25 MiB per file.
 */
export function limitProblem(files: ReadonlyArray<{ rel: string; bytes: number }>): string | null {
  if (files.length > MAX_FILES) {
    return `${files.length} files to publish, over the step's limit of ${MAX_FILES} (Pages allows 20,000 per deployment)`;
  }
  const big = files.find((f) => f.bytes > MAX_FILE_BYTES);
  if (big) {
    return `${big.rel} is ${mb(big.bytes)} MiB, over the step's limit of ${mb(MAX_FILE_BYTES)} MiB (Pages allows 25 MiB per file)`;
  }
  return null;
}

/** Where publishSource writes, for a given checkout. */
export function sourcePublicDir(paths: Paths, override?: string): string {
  return override ?? process.env.HOMEPAGE_PUBLIC_DIR ?? path.join(paths.monorepoRoot, "homepage", "public");
}

// The skip key, kept BESIDE the public dir, never in it: it holds the rules
// hash, and public/ is deployed. It is also what the homepage's deploy stage checks
// homepage/out's source against (publishedSourceProblem).
function statePath(publicDir: string): string {
  return path.join(path.dirname(publicDir), ".source-publish.json");
}

type PublishState = {
  sourceCommit: string;
  mirrorHead: string;
  // The rules, the literals and SOURCE_STEP_VERSION.
  rulesHash: string;
  // "<label> <version>": an upgrade may rewrite every id, so it re-publishes.
  filterRepo: string;
  // gitleaksIdentity(): a newer gitleaks may find what the old one did not,
  // so it re-publishes, and an out/ it never scanned does not deploy.
  gitleaks: string;
  // sourceDigest() over every published file: an out/ (or public/) holding
  // another publish's mirror or tree beside this manifest does not match.
  contentDigest: string;
  // stagitIdentity(): "absent", or which stagit rendered the history. An
  // install (or an upgrade) re-publishes.
  stagit: string;
  // The history pages as audited (historyDigest), or null when none were
  // published. A null beside a stagit that is present (a render that failed,
  // pages over the limits) never skips: the next build tries again.
  history: { files: number; digest: string } | null;
};

/**
 * One digest over every file a publish puts on the site, under `root` laid
 * out as public/ and out/ both are: `source/archilyzer.git/**`,
 * `source/tree/**`, `source/git/**`, `source/manifest.json`,
 * `downloads/archilyzer-source.tar.gz` and `downloads/snapshot.json`. Each
 * file contributes its relative path, size and sha256 (streamed), in sorted
 * path order; a symlink or a missing piece contributes a marker, so it can
 * only differ. The /source PAGE and anything else Next writes beside them are
 * not part of it.
 */
export async function sourceDigest(root: string): Promise<string> {
  return digestOf(root, [
    `source/${MIRROR_DIR}`,
    "source/tree",
    `source/${HISTORY_DIR}`,
    "source/manifest.json",
    `downloads/${TARBALL_NAME}`,
    "downloads/snapshot.json",
  ]);
}

/**
 * The same digest over the history pages alone (`source/git/**`): the
 * manifest's `history.sha256`, and what the deploy check recomputes over
 * out/ to name a history that is not the audited one.
 */
export async function historyDigest(root: string): Promise<string> {
  return digestOf(root, [`source/${HISTORY_DIR}`]);
}

async function digestOf(root: string, tops: readonly string[]): Promise<string> {
  const entries: string[] = [];
  const walk = async (rel: string): Promise<void> => {
    const abs = path.join(root, rel);
    const st = await lstat(abs).catch(() => null);
    if (!st) {
      entries.push(`${rel}\0missing`);
    } else if (st.isSymbolicLink()) {
      entries.push(`${rel}\0symlink`);
    } else if (st.isDirectory()) {
      for (const name of await readdir(abs)) await walk(`${rel}/${name}`);
    } else {
      entries.push(`${rel}\0${st.size}\0${await sha256File(abs)}`);
    }
  };
  for (const top of tops) await walk(top);
  entries.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
  const h = createHash("sha256");
  for (const e of entries) h.update(`${e}\n`);
  return h.digest("hex");
}

/**
 * Which gitleaks the audit runs: "skipped" (none asked for), "absent" (not on
 * PATH), else its version line and the sha256 of its binary — the version
 * line alone is not enough (a distribution build can print the same line for
 * every release).
 */
export async function gitleaksIdentity(bin: string | null, env: NodeJS.ProcessEnv): Promise<string> {
  if (bin === null) return "skipped";
  const found = onPath(bin, env.PATH);
  if (!found) return "absent";
  const version = await new Promise<string>((resolve) => {
    execFile(found, ["version"], { env, timeout: 10_000 }, (_err, stdout, stderr) =>
      resolve(String(stdout || stderr).trim().split("\n")[0] ?? ""),
    );
  });
  const sha = await sha256File(await realpath(found));
  return `${version || "unknown version"} (${sha.slice(0, 12)})`;
}

async function readJson(file: string): Promise<unknown> {
  try {
    return JSON.parse(await readFile(file, "utf8"));
  } catch {
    return null;
  }
}

/** The last published manifest in `publicDir`, or null. */
export async function readPublishedManifest(publicDir: string): Promise<SourceManifest | null> {
  return parseSourceManifest(await readJson(path.join(publicDir, "source", "manifest.json")));
}

/** Said, and nothing mirrored, in a checkout without git history. */
export const NO_REPOSITORY =
  "no git repository here; nothing to mirror — the /source page will show its empty state";

/**
 * Remove a publish from `publicDir`: the manifest FIRST (the page never
 * describes a half-removed tree), the skip key, the mirror, the tree and the
 * history pages, the tarball and snapshot.json. Link-safe like the install: a
 * linked `source/` or `downloads/` (a worktree's, into the primary) goes as a
 * link, its target untouched. True when there was something to remove.
 */
export async function removePublishedSource(publicDir: string): Promise<boolean> {
  const pubSource = path.join(publicDir, "source");
  const pubDownloads = path.join(publicDir, "downloads");
  const had =
    existsSync(path.join(pubSource, "manifest.json")) ||
    existsSync(path.join(pubSource, MIRROR_DIR)) ||
    existsSync(path.join(pubSource, HISTORY_DIR)) ||
    existsSync(path.join(pubDownloads, TARBALL_NAME));
  await rm(path.join(pubSource, "manifest.json"), { force: true });
  await rm(statePath(publicDir), { force: true });
  // fs.rm reads the path with lstat: a linked public/source goes as a link.
  await rm(pubSource, { recursive: true, force: true });
  const linked = await lstat(pubDownloads).then((s) => s.isSymbolicLink(), () => false);
  if (linked) {
    await rm(pubDownloads, { force: true });
  } else {
    await rm(path.join(pubDownloads, "snapshot.json"), { force: true });
    await rm(path.join(pubDownloads, TARBALL_NAME), { force: true });
  }
  return had;
}

// The checkout's git common dir, or null when there is no repository here (or
// no git at all — a docker runtime, a tarball install).
async function commonDir(ctx: Ctx, cwd: string): Promise<string | null> {
  const r = await run(ctx, "git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
    cwd,
    timeoutMs: 30_000,
    allowFail: true,
  });
  if (r.code === 0) return lastLine(r.out);
  if (!onPath("git", ctx.env.PATH) || r.out.some((l) => /not a git repository/i.test(l))) return null;
  const tail = r.out.slice(-2).map((l) => maskLiterals(l, ctx.literals)).join(" / ");
  throw new SourceRefusal(`git rev-parse exited ${r.code}${tail ? `: ${tail}` : ""}`);
}

// The repository to mirror when the caller names none: ARCHILYZER_SOURCE_REPO
// when it is set — in a container, the host's git common dir mounted read-only
// by docker-compose.source.yml, since the image has no .git — else this
// checkout's common dir. A variable that names nothing is a refusal, not a
// silent fall-through to "no repository" (which would withdraw the publish
// with a sentence about tarball installs).
async function sourceRepoFor(ctx: Ctx, cwd: string): Promise<string | null> {
  const named = ctx.env.ARCHILYZER_SOURCE_REPO?.trim();
  if (named) {
    if (!existsSync(named)) {
      throw new SourceRefusal(
        `ARCHILYZER_SOURCE_REPO names ${named}, which is not there — mount the host's git common dir there (docker-compose.source.yml), or unset it`,
      );
    }
    return named;
  }
  return commonDir(ctx, cwd);
}

// The real path of `p`, or of its deepest existing ancestor with the rest
// appended: a scratch root may not exist yet, and a symlink must not hide
// where it lands.
async function landsAt(p: string): Promise<string> {
  const abs = path.resolve(p);
  let head = abs;
  const rest: string[] = [];
  for (;;) {
    try {
      return path.join(await realpath(head), ...rest);
    } catch {
      const up = path.dirname(head);
      if (up === head) return abs;
      rest.unshift(path.basename(head));
      head = up;
    }
  }
}

const within = (child: string, parent: string) =>
  child === parent || child.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);

/**
 * Why `scratchRoot` may not hold the scratch dir, or null. Inside the checkout
 * or the public dir, a kept scratch (`--keep-scratch`) could be committed or
 * published — and it held replace.txt, the scrub rules in plain text.
 */
export async function scratchRootProblem(
  scratchRoot: string,
  places: ReadonlyArray<[string, string]>,
): Promise<string | null> {
  const what = await insideOf(scratchRoot, places);
  return what
    ? `the scratch root ${tildify(scratchRoot)} (ARCHILYZER_SOURCE_SCRATCH) is inside ${what}, where a kept scratch dir could be committed or published — point it outside`
    : null;
}

// Which of `places` ([name, dir]) `p` lands inside, through symlinks, or null.
async function insideOf(p: string, places: ReadonlyArray<[string, string]>): Promise<string | null> {
  const at = await landsAt(p);
  for (const [what, dir] of places) {
    if (within(at, await landsAt(dir))) return what;
  }
  return null;
}

/**
 * The history's render cache for this publish, or null: none for `--check`
 * (it writes nothing outside its scratch), none when asked for none, and none
 * — with a line saying so — when it would land inside the checkout or the
 * public dir, where it could be committed or published.
 */
export async function historyCacheFor(
  opts: Pick<SourcePublishOpts, "check" | "historyCacheDir">,
  paths: Paths,
  publicDir: string,
  onLog: (line: string) => void,
): Promise<string | null> {
  if (opts.check) return null;
  const dir = opts.historyCacheDir === undefined ? (paths.sourceHistoryCacheDir ?? null) : opts.historyCacheDir;
  if (!dir) return null;
  const what = await insideOf(dir, [
    ["the checkout", paths.monorepoRoot],
    ["the public dir", publicDir],
  ]);
  if (what) {
    onLog(`[source] history: the render cache ${tildify(dir)} (XDG_CACHE_HOME) is inside ${what}; rendering without it`);
    return null;
  }
  return dir;
}

// ── the step ────────────────────────────────────────────────────────────────

/**
 * Publish the source (see the header). Returns 0 when published, skipped or
 * checked, 1 when refused or cancelled; the refusal's reason (and the audit's
 * report) is in the log. Throws only on a bug or an I/O failure.
 *
 * A REFUSAL WITHDRAWS THE PREVIOUS PUBLISH. Once the rules are loaded, any
 * outcome but success — an audit hit, a limit, a missing tool, a cancel, a
 * crash — removes what the last publish left (removePublishedSource): it was
 * audited under rules that may not be today's, and a refusal is the best
 * evidence that they are not. `--check` writes nothing, this included.
 *
 * `noRepository: "empty"` (buildHomepage) turns a checkout with no git
 * repository into an empty /source page and 0; the CLI's default refuses.
 */
export async function publishSource(opts: SourcePublishOpts = {}): Promise<number> {
  const paths = opts.paths ?? getPaths();
  const onLog = opts.onLog ?? terminalLog;
  const signal = opts.signal ?? new AbortController().signal;
  const ctx: Ctx = { onLog, signal, env: cleanGitEnv(opts.env ?? process.env), literals: [] };
  const publicDir = sourcePublicDir(paths, opts.publicDir);
  const progress = { rulesLoaded: false, historyCache: null as string | null };
  const withdraw = async () => {
    if (!progress.rulesLoaded || opts.check) return;
    if (await removePublishedSource(publicDir)) {
      onLog(
        "[source] the previous publish was WITHDRAWN (mirror, tree, history, tarball): it was audited under rules that may not be today's. /source shows its empty state until a publish passes.",
      );
    }
    // The history's render cache was rendered under those rules too. It is
    // never why a withdrawal fails: one line, and the refusal stands.
    if (progress.historyCache) {
      try {
        await dropHistoryCache(progress.historyCache);
      } catch (err) {
        const why = (err as NodeJS.ErrnoException)?.code ?? (err as Error)?.message ?? String(err);
        onLog(
          maskLiterals(
            `[source] the history's render cache ${tildify(progress.historyCache)} could not be removed (${why}); remove it by hand`,
            ctx.literals,
          ),
        );
      }
    }
  };
  let code: number;
  try {
    code = await publish(opts, paths, ctx, publicDir, progress);
  } catch (err) {
    if (err instanceof Cancelled || signal.aborted) {
      onLog("[source] cancelled — nothing published");
      code = 1;
    } else if (err instanceof SourceRefusal) {
      // A refusal may name a tree path or quote a child's stderr: masked, so
      // a literal spanning path components (`a/b`) is never printed.
      onLog(`[source] REFUSED: ${maskLiterals(err.message, ctx.literals)}`);
      code = 1;
    } else {
      await withdraw().catch(() => {});
      throw err;
    }
  }
  if (code !== 0) await withdraw();
  return code;
}

async function publish(
  opts: SourcePublishOpts,
  paths: Paths,
  ctx: Ctx,
  publicDir: string,
  progress: { rulesLoaded: boolean; historyCache: string | null },
): Promise<number> {
  const { onLog } = ctx;
  const started = Date.now();
  const pubSource = path.join(publicDir, "source");
  const pubDownloads = path.join(publicDir, "downloads");

  // 1. The private main — or no repository at all (L8: the docker runtime,
  // a tarball install), where nothing can be mirrored and nothing can leak.
  const sourceRepo = opts.sourceRepo ?? (await sourceRepoFor(ctx, paths.monorepoRoot));
  if (sourceRepo === null) {
    onLog(`[source] ${NO_REPOSITORY}`);
    if (opts.check) return 1;
    if (await removePublishedSource(publicDir)) onLog("[source] the previous publish was removed.");
    return opts.noRepository === "empty" ? 0 : 1;
  }
  const sourceCommit = await revParse(ctx, sourceRepo, `refs/heads/${SOURCE_BRANCH}^{commit}`);

  // 2. The operator's rules. From here on, a failure withdraws the last publish.
  const rules = await loadSourceRules({
    scrubFile: opts.scrubFile ?? paths.sourceScrubFile,
    denylistFile: opts.denylistFile ?? paths.sourceDenylistFile,
    homeDir: opts.homeDir,
  });
  ctx.literals = rules.literals;
  progress.rulesLoaded = true;

  // 3. The tools (the filter-repo version is part of the skip key).
  const filterRepo: FilterRepoChoice =
    opts.filterRepo && opts.filterRepo.length > 0
      ? { argv: opts.filterRepo, label: opts.filterRepo.join(" "), version: "(given)" }
      : await resolveFilterRepo({ env: ctx.env, signal: ctx.signal });
  const filterRepoId = `${filterRepo.label} ${filterRepo.version}`;
  const gitleaksBin = opts.gitleaks === undefined ? "gitleaks" : opts.gitleaks;
  const gitleaksId = await gitleaksIdentity(gitleaksBin, ctx.env);
  // stagit is optional: absent, the source is published without its history.
  const stagit =
    opts.stagit === undefined
      ? resolveStagit(paths.stagitBin ?? "stagit", ctx.env)
      : opts.stagit && existsSync(opts.stagit)
        ? opts.stagit
        : null;
  const stagitId = await stagitIdentity(stagit);

  // 4. Nothing changed: skip. The key is main, the rules (with the step's
  // version), the tools, and the published files themselves.
  if (!opts.force && !opts.check) {
    const manifest = await readPublishedManifest(publicDir);
    const state = (await readJson(statePath(publicDir))) as Partial<PublishState> | null;
    if (
      manifest?.sourceCommit === sourceCommit &&
      state?.sourceCommit === sourceCommit &&
      state.rulesHash === rules.rulesHash &&
      state.filterRepo === filterRepoId &&
      state.gitleaks === gitleaksId &&
      state.stagit === stagitId &&
      (stagitId === "absent" ? state.history === null : !!state.history) &&
      state.mirrorHead === manifest.mirrorHead &&
      existsSync(path.join(pubSource, MIRROR_DIR, "info", "refs")) &&
      existsSync(path.join(pubDownloads, TARBALL_NAME)) &&
      state.contentDigest === (await sourceDigest(publicDir))
    ) {
      onLog(`[source] up to date at ${sourceCommit.slice(0, 12)}; skipping (--force to rebuild)`);
      return 0;
    }
  }
  if (existsSync(path.join(pubSource, "index.html"))) {
    throw new SourceRefusal(
      `${tildify(path.join(pubSource, "index.html"))} exists and would replace the /source/ page — remove it`,
    );
  }
  const gitVersion = lastLine((await run(ctx, "git", ["--version"], { cwd: os.tmpdir(), timeoutMs: 30_000 })).out)
    .replace(/^git version /, "");
  onLog(`[source] main ${sourceCommit.slice(0, 12)}; git ${gitVersion}; ${filterRepoId}`);

  const scratchRoot = opts.scratchRoot ?? paths.sourceScratchDir;
  const badRoot = await scratchRootProblem(scratchRoot, [
    ["the checkout", paths.monorepoRoot],
    ["the public dir", publicDir],
  ]);
  if (badRoot) throw new SourceRefusal(badRoot);
  // From here a refusal removes the history's render cache too.
  const historyCache = await historyCacheFor(opts, paths, publicDir, (l) => onLog(maskLiterals(l, ctx.literals)));
  progress.historyCache = historyCache;
  await mkdir(scratchRoot, { recursive: true });
  const scratch = await mkdtemp(path.join(scratchRoot, "archilyzer-source-"));
  const replace = path.join(scratch, "replace.txt");
  try {
    // Named as the published mirror is: stagit names the repository after its
    // directory ("archilyzer", the `.git` dropped).
    const bare = path.join(scratch, MIRROR_DIR);

    // 5. A fresh bare clone of main alone. --no-local: through upload-pack, not
    // a copy of the object dir (which would carry every loose leftover).
    await run(
      ctx,
      "git",
      ["clone", "--no-local", "--bare", "--single-branch", "--no-tags", "--branch", SOURCE_BRANCH, "--quiet", sourceRepo, bare],
      { cwd: scratch, timeoutMs: 120_000 },
    );
    await run(ctx, "git", ["--git-dir", bare, "remote", "remove", "origin"], { cwd: bare, timeoutMs: 30_000 });

    // 6. The rewrite. --force: filter-repo wants a fresh clone with an origin.
    await writeFile(replace, rules.scrub.lines.join("\n") + "\n", { mode: 0o600 });
    onLog(`[source] rewriting history (${rules.scrub.lines.length} scrub rule${rules.scrub.lines.length === 1 ? "" : "s"})…`);
    await run(
      ctx,
      filterRepo.argv[0],
      [
        ...filterRepo.argv.slice(1),
        "--force",
        "--quiet",
        "--replace-refs",
        "delete-no-add",
        "--replace-text",
        replace,
        "--replace-message",
        replace,
      ],
      { cwd: bare, timeoutMs: 900_000, echo: true },
    );
    // commit-map / ref-map hold the PRIVATE ids.
    await rm(path.join(bare, "filter-repo"), { recursive: true, force: true });

    // 7. Packed for dumb HTTP.
    const g = (args: string[], timeoutMs = 60_000) =>
      run(ctx, "git", ["--git-dir", bare, ...args], { cwd: bare, timeoutMs });
    await g(["repack", "-a", "-d", "-q", `--max-pack-size=${PACK_SIZE}`], 300_000);
    await g(["prune-packed"]);
    await g(["pack-refs", "--all"]);
    await g(["update-server-info"]);
    const counts = (await g(["count-objects", "-v"])).out;
    const loose = Number(/^count:\s*(\d+)/m.exec(counts.join("\n"))?.[1] ?? NaN);
    if (loose !== 0) throw new SourceRefusal(`the repacked mirror still has ${loose} loose objects`);
    const packsList = await readFile(path.join(bare, "objects", "info", "packs"), "utf8").catch(() => "");
    const packs = packsList.split("\n").filter((l) => l.startsWith("P ")).length;
    if (packs === 0) throw new SourceRefusal("the repacked mirror lists no packs in objects/info/packs");
    const refs = (await g(["for-each-ref", "--format=%(refname)"])).out.filter((l) => l.trim());
    if (refs.length !== 1 || refs[0] !== `refs/heads/${SOURCE_BRANCH}`) {
      throw new SourceRefusal(`the mirror must hold refs/heads/${SOURCE_BRANCH} alone, and holds ${refs.length} refs`);
    }
    const head = (await readFile(path.join(bare, "HEAD"), "utf8")).trim();
    if (head !== `ref: refs/heads/${SOURCE_BRANCH}`) {
      throw new SourceRefusal(`the mirror's HEAD is not refs/heads/${SOURCE_BRANCH}`);
    }

    // 8. What it became.
    const mirrorHead = await revParse(ctx, bare, `refs/heads/${SOURCE_BRANCH}`);
    const subject = lastLine((await g(["log", "-1", "--format=%s", `refs/heads/${SOURCE_BRANCH}`])).out);

    // 9. THE GATE, over every object.
    onLog(`[source] auditing ${mirrorHead.slice(0, 12)} for ${rules.literals.length} denied literals…`);
    const audit = await auditBare(bare, rules.literals, {
      scratch,
      onLog,
      signal: ctx.signal,
      gitleaks: gitleaksBin,
      env: ctx.env,
    });
    const scrubFile = opts.scrubFile ?? paths.sourceScrubFile;
    if (audit.hits.length > 0) {
      for (const l of formatAuditReport(audit, rules.literals, { scrubFile })) onLog(l);
      return 1;
    }

    const now = opts.now?.() ?? new Date();
    const generatedAt = now.toISOString();
    const stage = path.join(scratch, "stage");
    const stageSource = path.join(stage, "source");
    const stageMirror = path.join(stageSource, MIRROR_DIR);
    const stageTree = path.join(stageSource, "tree");
    const stageDownloads = path.join(stage, "downloads");
    await mkdir(stageTree, { recursive: true });
    await mkdir(stageDownloads, { recursive: true });

    // 10. The raw tree, with its directory pages.
    const treeTar = path.join(scratch, "tree.tar");
    await g(["archive", "--format=tar", "-o", treeTar, `refs/heads/${SOURCE_BRANCH}`], 120_000);
    await run(ctx, "tar", ["-xf", treeTar, "-C", stageTree], { cwd: scratch, timeoutMs: 120_000 });
    await rm(treeTar, { force: true });
    const tree = await writeTreeIndexes(stageTree, { mirrorHead, generatedAt });

    // 11. The tarball and its sidecar (the Snapshot shape the Downloads page reads).
    const tarball = path.join(stageDownloads, TARBALL_NAME);
    await g(
      ["archive", "--format=tar.gz", "-9", "--prefix=archilyzer/", "-o", tarball, `refs/heads/${SOURCE_BRANCH}`],
      120_000,
    );
    const tarBytes = (await stat(tarball)).size;
    const tarSha = await sha256File(tarball);
    const snapshotText =
      JSON.stringify(
        { generatedAt, commit: mirrorHead, subject, bytes: tarBytes, sha256: tarSha },
        null,
        2,
      ) + "\n";
    await writeFile(path.join(stageDownloads, "snapshot.json"), snapshotText);

    // 12. The mirror, from an ALLOWLIST: never config (it names the clone's
    // origin path), hooks/, description, logs/, filter-repo/, *.rev, *.bitmap.
    // refs/heads/<branch> is written beside packed-refs so the directory is a
    // git dir to git itself too (a file:// clone, `source audit`): git wants a
    // refs/ directory, and an empty one would not survive the deploy.
    await mkdir(path.join(stageMirror, "info"), { recursive: true });
    await mkdir(path.join(stageMirror, "objects", "info"), { recursive: true });
    await mkdir(path.join(stageMirror, "objects", "pack"), { recursive: true });
    await mkdir(path.join(stageMirror, "refs", "heads"), { recursive: true });
    for (const f of ["HEAD", "packed-refs", "info/refs", "objects/info/packs"]) {
      await cp(path.join(bare, f), path.join(stageMirror, f));
    }
    await writeFile(path.join(stageMirror, "refs", "heads", SOURCE_BRANCH), `${mirrorHead}\n`);
    for (const f of await readdir(path.join(bare, "objects", "pack"))) {
      if (/^pack-[0-9a-f]+\.(pack|idx)$/.test(f)) {
        await cp(path.join(bare, "objects", "pack", f), path.join(stageMirror, "objects", "pack", f));
      }
    }
    const mirrorFiles = await walkFiles(stageMirror);

    // 12b. The history pages (stagit), rendered from the audited mirror into
    // the stage, so the file gate (13) reads every page. Without stagit — or
    // when the render fails, or would break the host's limits — one line says
    // so and the rest is published without them: never a failed build.
    const stageHistoryDir = path.join(stageSource, HISTORY_DIR);
    let history: SourceHistory | null = null;
    if (!stagit) {
      const why = (paths.stagitBin ?? "stagit").includes("/")
        ? "STAGIT_BIN names no executable"
        : "not on PATH, not in ~/.local/bin";
      onLog(
        `[source] stagit not found (${why}) — publishing without the history pages (/source/${HISTORY_DIR}/); install it once: ${STAGIT_INSTALL}`,
      );
    } else {
      const commits = Number(lastLine((await g(["rev-list", "--count", `refs/heads/${SOURCE_BRANCH}`])).out));
      history = await stageHistoryPages({
        ctx,
        opts,
        paths,
        stagit,
        stagitId,
        bare,
        mirrorHead,
        commits,
        scratch,
        historyCache,
        rulesHash: rules.rulesHash,
        filterRepoId,
        stage,
        dest: stageHistoryDir,
        // The raw tree's files, as tracked: links to any other become text.
        treeFiles: new Set((await walkFiles(stageTree)).map((f) => f.rel)),
        // Everything staged so far, and the manifest still to come.
        stagedSoFar: (await walkFiles(stage)).length + 1,
      });
    }

    // The manifest, staged with the rest so the file sweep reads it too. It
    // carries no rules hash and no literal count: `plans/` publishes which
    // literals the plan put in the files, so either would say whether the
    // operator added private ones — and the hash would confirm a guess.
    const staged = await walkFiles(stage);
    const manifest: SourceManifest = {
      version: SOURCE_MANIFEST_VERSION,
      generatedAt,
      branch: SOURCE_BRANCH,
      sourceCommit,
      mirrorHead,
      subject,
      files: staged.length,
      bytes: staged.reduce((n, f) => n + f.bytes, 0),
      mirror: {
        files: mirrorFiles.length,
        bytes: mirrorFiles.reduce((n, f) => n + f.bytes, 0),
        packs,
      },
      tree,
      tarball: { href: TARBALL_HREF, bytes: tarBytes, sha256: tarSha },
      cloneUrl: CLONE_URL,
      treeHref: TREE_HREF,
      audit: {
        objects: audit.objects,
        commits: audit.commits,
        gitleaks: audit.gitleaks === "clean" ? "clean" : "skipped",
      },
      tools: { git: gitVersion, filterRepo: filterRepoId },
      ...(history ? { history } : {}),
    };
    const manifestText = JSON.stringify(manifest, null, 2) + "\n";
    await writeFile(path.join(stageSource, "manifest.json"), manifestText);
    // Every published file, as it will land: the state carries it, and the
    // skip and the deploy check recompute it over public/ and out/.
    const contentDigest = await sourceDigest(stage);

    // 13. THE GATE, over every staged file and path (packs excepted: step 9
    // read their objects).
    await auditFiles(stage, rules.literals, { result: audit });
    if (audit.hits.length > 0) {
      for (const l of formatAuditReport(audit, rules.literals, { scrubFile })) onLog(l);
      return 1;
    }
    for (const l of formatAuditReport(audit, rules.literals, { scrubFile })) onLog(l);

    // 14. The host's limits.
    const all = await walkFiles(stage);
    const tooMuch = limitProblem(all);
    if (tooMuch) throw new SourceRefusal(maskLiterals(tooMuch, rules.literals));
    const totalBytes = all.reduce((n, f) => n + f.bytes, 0);
    const summary =
      `main ${sourceCommit.slice(0, 12)} as ${mirrorHead.slice(0, 12)}: ${all.length} files, ${mb(totalBytes)} MB ` +
      `(mirror ${packs} pack${packs === 1 ? "" : "s"}, tree ${tree.dirs} dirs, ` +
      `${history ? `history ${history.commits < history.total ? `the latest ${history.commits} of ${history.total}` : history.commits} commits in ${history.files} files` : "no history"}), ` +
      `tarball ${mb(tarBytes)} MB sha256 ${tarSha.slice(0, 12)}`;

    // 15. --check writes nothing.
    if (opts.check) {
      onLog(`[source] check passed — would publish ${summary}; nothing written (${elapsed(started)})`);
      return 0;
    }

    // 16. Install, link-safe. The manifest goes first and comes back last: a
    // crash mid-copy leaves the page's empty state, never a manifest over a
    // half-written tree.
    await ownDir(pubSource);
    await rm(path.join(pubSource, "manifest.json"), { force: true });
    await rm(path.join(pubSource, MIRROR_DIR), { recursive: true, force: true });
    await rm(path.join(pubSource, "tree"), { recursive: true, force: true });
    await rm(path.join(pubSource, HISTORY_DIR), { recursive: true, force: true });
    await cp(stageMirror, path.join(pubSource, MIRROR_DIR), { recursive: true });
    await cp(stageTree, path.join(pubSource, "tree"), { recursive: true });
    if (history) await cp(stageHistoryDir, path.join(pubSource, HISTORY_DIR), { recursive: true });
    await ownDir(pubDownloads);
    await copyPublicFile(tarball, path.join(pubDownloads, TARBALL_NAME));
    await writePublicFile(path.join(pubDownloads, "snapshot.json"), snapshotText);
    const state: PublishState = {
      sourceCommit,
      mirrorHead,
      rulesHash: rules.rulesHash,
      filterRepo: filterRepoId,
      gitleaks: gitleaksId,
      contentDigest,
      stagit: stagitId,
      history: history ? { files: history.files, digest: history.sha256 } : null,
    };
    await writeFile(statePath(publicDir), JSON.stringify(state, null, 2) + "\n");
    await writePublicFile(path.join(pubSource, "manifest.json"), manifestText);

    // 17.
    onLog(`[source] published ${summary} (${elapsed(started)})`);
    return 0;
  } finally {
    if (opts.keepScratch) {
      // The scrub rules in plain text never outlive the run.
      await rm(replace, { force: true });
      onLog(`[source] scratch kept at ${maskLiterals(tildify(scratch), ctx.literals)} (replace.txt, the scrub rules, deleted)`);
    } else {
      await rm(scratch, { recursive: true, force: true });
    }
  }
}

function elapsed(started: number): string {
  return `${Math.round((Date.now() - started) / 1000)} s`;
}

/**
 * Step 12b: render the history pages into `a.dest` (stage/source/git) and say
 * what they are, or say why not and leave no `dest` — a WARNING, never a
 * refusal: the tokens unreadable, stagit failing, or pages that would break
 * the host's limits (the step's, which step 14 applies to the whole publish).
 * A cancel still cancels.
 */
async function stageHistoryPages(a: {
  ctx: Ctx;
  opts: SourcePublishOpts;
  paths: Paths;
  stagit: string;
  stagitId: string;
  bare: string;
  mirrorHead: string;
  commits: number;
  scratch: string;
  historyCache: string | null;
  rulesHash: string;
  filterRepoId: string;
  stage: string;
  dest: string;
  treeFiles: ReadonlySet<string>;
  stagedSoFar: number;
}): Promise<SourceHistory | null> {
  const { ctx } = a;
  const started = Date.now();
  const where = `/source/${HISTORY_DIR}/`;
  const without = async (why: string): Promise<null> => {
    await rm(a.dest, { recursive: true, force: true });
    ctx.onLog(`[source] WARNING: ${maskLiterals(why, ctx.literals)} — publishing without the history pages (${where})`);
    return null;
  };
  const tokensFile =
    a.opts.tokensFile ??
    path.join(/* turbopackIgnore: true */ a.paths.monorepoRoot, "common", "styles", "tokens.css");
  let stylesheet: string;
  try {
    stylesheet = historyStylesheet(await readFile(tokensFile, "utf8"));
  } catch (err) {
    if (err instanceof HistoryProblem) return without(err.message);
    return without(`the design tokens (${tildify(tokensFile)}) could not be read`);
  }
  // stagit and git through the step's own runner (the environment, the
  // cancel, the timeout); a failure or a timeout is the history's problem.
  const child: HistoryRun = async (command, args, o) => {
    try {
      return await run(ctx, command, args, { ...o, allowFail: true });
    } catch (err) {
      if (err instanceof SourceRefusal) throw new HistoryProblem(err.message);
      throw err;
    }
  };
  const baseUrl = `${PROJECT_URL}${where}`;
  let r;
  try {
    r = await renderHistory({
      stagit: a.stagit,
      gitDir: a.bare,
      head: a.mirrorHead,
      commits: a.commits,
      maxCommits: a.opts.maxHistoryCommits ?? SOURCE_HISTORY_MAX_COMMITS,
      dest: a.dest,
      scratch: a.scratch,
      cacheDir: a.historyCache,
      cacheKey: historyCacheKey({
        rulesHash: a.rulesHash,
        filterRepo: a.filterRepoId,
        stagit: a.stagitId,
        description: PROJECT_NAME,
        cloneUrl: CLONE_URL,
        baseUrl,
      }),
      fresh: !!a.opts.force,
      description: PROJECT_NAME,
      cloneUrl: CLONE_URL,
      baseUrl,
      stylesheet,
      themeScript: homepageThemeScript(),
      treeFiles: a.treeFiles,
      run: child,
      // stagit's words (a failure's tail, a timeout's argv) can name the home
      // dir: every line is masked, as every other child line of the step is.
      onLog: (l) => ctx.onLog(maskLiterals(l, ctx.literals)),
    });
  } catch (err) {
    if (err instanceof HistoryProblem) return without(`the history pages were not rendered: ${err.message}`);
    throw err;
  }
  const fileLimit = a.opts.historyFileLimit ?? MAX_FILES;
  if (a.stagedSoFar + r.files > fileLimit) {
    return without(
      `${r.files} history files would make ${a.stagedSoFar + r.files} files to publish, over the step's limit of ${fileLimit} (Pages allows 20,000 per deployment)`,
    );
  }
  if (r.largest.bytes > MAX_FILE_BYTES) {
    return without(
      `${HISTORY_DIR}/${r.largest.rel} is ${mb(r.largest.bytes)} MiB, over the step's limit of ${mb(MAX_FILE_BYTES)} MiB (Pages allows 25 MiB per file)`,
    );
  }
  const sha256 = await historyDigest(a.stage);
  ctx.onLog(
    `[source] history: ${a.stagitId} — ${r.shown < a.commits ? `the latest ${r.shown} of ${a.commits}` : a.commits} commits, ${r.rendered} page${r.rendered === 1 ? "" : "s"} rendered` +
      `${r.cached ? " (the rest from the cache)" : ""}; ${r.files} files, ${mb(r.bytes)} MB, ` +
      `the largest ${HISTORY_DIR}/${r.largest.rel} ${mb(r.largest.bytes)} MB (${elapsed(started)})`,
  );
  return {
    href: HISTORY_LOG_HREF,
    commits: r.shown,
    total: a.commits,
    head: a.mirrorHead,
    files: r.files,
    bytes: r.bytes,
    sha256,
    tool: a.stagitId,
  };
}

/**
 * `build homepage --no-source`: remove what an earlier publish left, because
 * it was audited against the rules of ITS day. The pages then show their
 * empty states.
 */
export async function clearPublishedSource(
  opts: PublishOpts & { publicDir?: string } = {},
): Promise<void> {
  const paths = opts.paths ?? getPaths();
  const onLog = opts.onLog ?? terminalLog;
  const had = await removePublishedSource(sourcePublicDir(paths, opts.publicDir));
  onLog(
    had
      ? "[notice] --no-source: the previously published source (mirror, tree, history, tarball) was removed — this build ships none.\n"
      : "[notice] --no-source: no source published in this build.\n",
  );
}

/**
 * Why homepage/out's source may not be deployed, as one sentence — or null.
 * The homepage's deploy stage asks before every deploy, production and preview alike: a
 * deploy-only ships `out/` as the last build left it, and that build's source
 * was audited under the rules of its day. It deploys only when the last
 * publish (the skip key beside public/) was made under TODAY's rules and step
 * (`rulesHash`), of TODAY's `main`, and is the one in `out/` (its mirror head,
 * its tarball). An `out/` whose /source page shows the empty state — a
 * `--no-source` build — deploys as it always has; one with no /source page at
 * all (a refused build) does not.
 */
export async function publishedSourceProblem(
  paths: Paths,
  outDir: string,
  opts: {
    publicDir?: string;
    scrubFile?: string;
    denylistFile?: string;
    homeDir?: string;
    sourceRepo?: string;
    env?: NodeJS.ProcessEnv;
    // The gitleaks the audit would run (default "gitleaks"; null: none).
    gitleaks?: string | null;
  } = {},
): Promise<string | null> {
  const outSource = path.join(outDir, "source");
  const outTarball = path.join(outDir, "downloads", TARBALL_NAME);
  // The stage, not the bare `build homepage`: only a stage stamps the build
  // (`_homepage/built.json`), and a deploy ships what is stamped.
  const rebuild = "run `archilyzer publish homepage` (it re-audits), then deploy";
  // The /source/ PAGE is always in a finished build (it renders its empty
  // state without a publish). Without it, the build's source step refused —
  // it took out/source away — or the build predates the page.
  if (!existsSync(path.join(outSource, "index.html"))) {
    return `homepage/out has no /source page (its source step refused, or the build predates it) — ${rebuild}`;
  }
  const artefacts = [
    path.join(outSource, "manifest.json"),
    path.join(outSource, MIRROR_DIR),
    path.join(outSource, "tree"),
    path.join(outSource, HISTORY_DIR),
    outTarball,
  ];
  // A `--no-source` build: the page's empty state and nothing else.
  if (!artefacts.some((a) => existsSync(a))) return null;
  const manifest = parseSourceManifest(await readJson(path.join(outSource, "manifest.json")));
  if (!manifest) return `homepage/out holds a source publish without a valid manifest — ${rebuild}`;
  const state = (await readJson(statePath(sourcePublicDir(paths, opts.publicDir)))) as Partial<PublishState> | null;
  if (!state?.rulesHash || !state.mirrorHead || !state.sourceCommit || !state.contentDigest || !state.gitleaks) {
    return `homepage/out's source has no record of the rules it was audited under — ${rebuild}`;
  }
  let rules: SourceRules;
  try {
    rules = await loadSourceRules({
      scrubFile: opts.scrubFile ?? paths.sourceScrubFile,
      denylistFile: opts.denylistFile ?? paths.sourceDenylistFile,
      homeDir: opts.homeDir,
    });
  } catch (err) {
    if (err instanceof SourceRefusal) return `${err.message}; homepage/out's source cannot be checked`;
    throw err;
  }
  if (state.rulesHash !== rules.rulesHash) {
    return `homepage/out's source was audited under other rules (or an older version of the step) — ${rebuild}`;
  }
  if (state.mirrorHead !== manifest.mirrorHead) {
    return `homepage/out's source (${manifest.mirrorHead.slice(0, 12)}) is not the last publish (${state.mirrorHead.slice(0, 12)}) — ${rebuild}`;
  }
  const ctx: Ctx = {
    onLog: () => {},
    signal: new AbortController().signal,
    env: cleanGitEnv(opts.env ?? process.env),
    literals: rules.literals,
  };
  let main: string | null = null;
  try {
    const repo = opts.sourceRepo ?? (await sourceRepoFor(ctx, paths.monorepoRoot));
    main = repo ? await revParse(ctx, repo, `refs/heads/${SOURCE_BRANCH}^{commit}`) : null;
  } catch (err) {
    if (!(err instanceof SourceRefusal)) throw err;
  }
  if (main === null) return `homepage/out holds a source publish, and main cannot be read here — ${rebuild}`;
  if (main !== state.sourceCommit || main !== manifest.sourceCommit) {
    return `homepage/out's source mirrors main at ${manifest.sourceCommit.slice(0, 12)}, and main is now ${main.slice(0, 12)} — ${rebuild}`;
  }
  if (existsSync(outTarball) && (await sha256File(outTarball)) !== manifest.tarball.sha256) {
    return `homepage/out's source tarball is not the one its manifest describes — ${rebuild}`;
  }
  const env = cleanGitEnv(opts.env ?? process.env);
  const gitleaks = await gitleaksIdentity(opts.gitleaks === undefined ? "gitleaks" : opts.gitleaks, env);
  if (state.gitleaks !== gitleaks) {
    return `homepage/out's source was scanned by another gitleaks (${state.gitleaks}; this machine has ${gitleaks}) — ${rebuild}`;
  }
  // The history pages: exactly the audited ones, or none when none were
  // published. The digest below binds them too; this names them.
  const historyNow = existsSync(path.join(outSource, HISTORY_DIR)) ? await historyDigest(outDir) : null;
  const historyThen = state.history?.digest ?? null;
  if (historyNow !== historyThen || (manifest.history?.sha256 ?? null) !== historyThen) {
    return `homepage/out's history pages (/source/${HISTORY_DIR}/) are not the ones that were audited — ${rebuild}`;
  }
  // Last, and the one that binds every byte: the mirror, the tree, the
  // manifest and both downloads, against the digest of what was audited.
  if ((await sourceDigest(outDir)) !== state.contentDigest) {
    return `homepage/out's source files are not the ones that were audited (a mixed or edited out/) — ${rebuild}`;
  }
  return null;
}

// ── `archilyzer source audit` ───────────────────────────────────────────────

/**
 * The gate alone, over any git dir — by default the published mirror; the
 * rollout runs it on a LIVE clone. 0 clean, 1 hits (the redacted report is
 * logged) or refused.
 */
export async function auditSource(
  opts: PublishOpts & {
    gitDir?: string;
    publicDir?: string;
    scrubFile?: string;
    denylistFile?: string;
    gitleaks?: string | null;
    scratchRoot?: string;
    env?: NodeJS.ProcessEnv;
    homeDir?: string;
  } = {},
): Promise<number> {
  const paths = opts.paths ?? getPaths();
  const onLog = opts.onLog ?? terminalLog;
  const signal = opts.signal ?? new AbortController().signal;
  const env = cleanGitEnv(opts.env ?? process.env);
  const gitDir = path.resolve(
    opts.gitDir ?? path.join(sourcePublicDir(paths, opts.publicDir), "source", MIRROR_DIR),
  );
  const scrubFile = opts.scrubFile ?? paths.sourceScrubFile;
  let scratch: string | null = null;
  let literals: readonly Literal[] = [];
  try {
    const rules = await loadSourceRules({
      scrubFile,
      denylistFile: opts.denylistFile ?? paths.sourceDenylistFile,
      homeDir: opts.homeDir,
    });
    literals = rules.literals;
    const ctx: Ctx = { onLog, signal, env, literals: rules.literals };
    const head = await revParse(ctx, gitDir, "HEAD");
    const scratchRoot = opts.scratchRoot ?? paths.sourceScratchDir;
    await mkdir(scratchRoot, { recursive: true });
    scratch = await mkdtemp(path.join(scratchRoot, "archilyzer-source-audit-"));
    onLog(`[source] auditing ${maskLiterals(tildify(gitDir), literals)} (HEAD ${head.slice(0, 12)}) for ${rules.literals.length} denied literals…`);
    const audit = await auditBare(gitDir, rules.literals, {
      scratch,
      onLog,
      signal,
      gitleaks: opts.gitleaks === undefined ? "gitleaks" : opts.gitleaks,
      env,
    });
    for (const l of formatAuditReport(audit, rules.literals, { scrubFile })) onLog(l);
    return audit.hits.length > 0 ? 1 : 0;
  } catch (err) {
    if (err instanceof Cancelled || signal.aborted) {
      onLog("[source] cancelled");
      return 1;
    }
    if (err instanceof SourceRefusal) {
      onLog(`[source] REFUSED: ${maskLiterals(err.message, literals)}`);
      return 1;
    }
    throw err;
  } finally {
    if (scratch) await rm(scratch, { recursive: true, force: true });
  }
}