/**
 * Code-graph discovery: the indexes workers query instead of grepping, and the
 * commands that create and refresh them.
 *
 * Why this exists at all, measured on the dogfood fleet rather than assumed:
 * workers spend roughly four fifths of a 120-turn budget *finding* code — 30–62
 * `read` calls and 32–69 `bash` calls against 9–24 edits per run, 215–390k
 * characters of tool output. A code graph answers "who calls this" and "where is
 * this defined" in one call, which is the difference between a run that lands
 * and a run that dies mid-refactor with the work unfinished.
 *
 * Two hard boundaries hold everything here together:
 *
 * - **This package never builds or mutates an index, and never depends on the
 *   indexer for dispatch.** The optional health surface runs the indexer's
 *   read-only `list_projects` query; nothing spawns the graph server or imports
 *   it. `setup graph` renders a script and two systemd units per project and
 *   stages them only after its consent prompt — it does not enable them,
 *   because a package that silently writes root-level state is not one you can
 *   trust with a fleet.
 * - **A worker never queries its own worktree.** An index is keyed by the
 *   realpath of the directory it was built from, with no git-worktree awareness,
 *   so a run's `worktrees/<issue>` path is always an empty project. Workers are
 *   pointed at {@link RepoTarget.graphProject} — a conductor-owned clone nothing
 *   human edits — and {@link graphHint} is the text that makes that unmissable.
 */

import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir, userInfo } from "node:os";
import { dirname, join } from "node:path";
import { expandHome, stateDir } from "./config.ts";
import type { GraphToolsObservation, ProjectConfig, RepoTarget } from "./types.ts";

/**
 * The indexer's own CLI, invoked by name rather than by path so the generated
 * unit's explicit `PATH` is the single place a host's install location is
 * spelled out. `cli <tool> <json>` runs one tool without an MCP session.
 */
const INDEXER = "codebase-memory-mcp";

/**
 * The MCP server name the graph tools arrive under in a session's registry,
 * in the spellings the harness prefixes tools with (#726). `graphToolsPresent`
 * matches against these, so the runtime observation and `resolvePrereqs`'s
 * config check share one identity and cannot drift apart. The underscore form
 * is the harness's normalised spelling for a server name; the verbatim form
 * covers servers that keep their hyphens.
 */
export const GRAPH_MCP_SERVER_NAMES: readonly string[] = [INDEXER, INDEXER.replace(/-/g, "_")];

/**
 * Whether the code-graph tools are in a live session's registry (#726).
 *
 * Takes the session's own enabled tool names and matches the harness's MCP
 * mounting convention (`mcp__<server>_<tool>`). This is the runtime
 * observation: unlike {@link resolvePrereqs}'s `mounted` (which reads
 * `mcp.json` and can only say what a session should mount), it answers what
 * the session actually had, so "the model ignored a tool it had" and "the
 * tool was missing" stop looking identical from outside the session.
 */
export function graphToolsPresent(toolNames: readonly string[]): boolean {
  return toolNames.some(
    (name) =>
      name.startsWith("mcp__") &&
      GRAPH_MCP_SERVER_NAMES.some((server) => name.startsWith(`mcp__${server}_`)),
  );
}

/**
 * Poll a session's registry for the code-graph observation (#726).
 *
 * Measured against the real harness rather than assumed: MCP wiring finalises
 * after `createAgentSession` resolves (a deferred discovery pass), so the
 * registry read can throw in the window right after session creation, and the
 * graph tools surface under the *enabled* names — the active names stop at
 * the core tools. This therefore polls the enabled surface until the read
 * stops throwing, bounded by `deadlineMs`; a surface that never becomes
 * readable (or a build that does not expose one — `getEnabledToolNames` is
 * `undefined`) records *no* observation — never "graph tools absent", which
 * is the `present: false` truth value of a surface that was read.
 *
 * @param getEnabledToolNames the session's `getEnabledToolNames` read, already
 *   bound to its session (the SDK method dereferences private state), or
 *   `undefined` when the harness surface is absent
 */
export async function observeGraphTools(
  getEnabledToolNames: (() => string[]) | undefined,
  options: { intervalMs?: number; deadlineMs?: number } = {},
): Promise<GraphToolsObservation | undefined> {
  if (getEnabledToolNames === undefined) return undefined;
  const intervalMs = options.intervalMs ?? 250;
  const deadlineMs = options.deadlineMs ?? 15_000;
  const start = Date.now();
  for (;;) {
    try {
      return { present: graphToolsPresent(getEnabledToolNames()), at: Date.now() };
    } catch {
      if (Date.now() - start >= deadlineMs) return undefined;
      const { promise, resolve } = Promise.withResolvers<void>();
      setTimeout(resolve, intervalMs);
      await promise;
    }
  }
}

/** The shared prefix of every reindex artefact; `cbm` is the indexer's own prefix. */
export const REINDEX_UNIT = "cbm-reindex";

/** Where a system timer has to live to be enabled by `systemctl`. */
export const SYSTEMD_UNIT_DIR = "/etc/systemd/system";

/**
 * The filename-safe stem one project's reindex artefacts share:
 * `cbm-reindex-<slug>`. The slug is the project name folded to `[a-z0-9-]` —
 * the alphabet systemd unit names tolerate — with a deterministic hash
 * fallback for a name that folds to nothing, so every configured project gets
 * its own script, service and timer on the same host and one project's
 * `setup graph` can never replace another's files. The #720 incident was
 * exactly one project-less set of names, silently overwritten by the second
 * project's run.
 *
 * Two distinct names can fold to one stem ("My Project" vs "my_project"), so
 * the write path checks each target's generated-for marker before replacing
 * it rather than trusting the stem alone.
 */
export function reindexUnitName(p: ProjectConfig): string {
  const name = p.name;
  const slug = name
    .normalize("NFKD")
    .replace(/\p{Diacritic}/gu, "")
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "");
  if (slug !== "") return `${REINDEX_UNIT}-${slug}`;
  let hash = 2166136261;
  for (const byte of new TextEncoder().encode(name)) {
    hash ^= byte;
    hash = Math.imul(hash, 16777619) >>> 0;
  }
  return `${REINDEX_UNIT}-project-${hash.toString(16).padStart(8, "0")}`;
}

/**
 * Where this project's generated refresh script lands: conductor state, not a
 * unit directory, because it is ours to regenerate and needs no root to write.
 */
export function reindexScriptPath(p: ProjectConfig): string {
  return join(stateDir(), `${reindexUnitName(p)}.sh`);
}

/** Both unit files, from the stem `systemctl enable` will be given. */
export function unitPaths(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): { service: string; timer: string } {
  const stem = reindexUnitName(p);
  return {
    service: join(unitDir, `${stem}.service`),
    timer: join(unitDir, `${stem}.timer`),
  };
}

/** The `project "<name>"` marker every generated file carries: the script's
 *  first header line, and both units' Description. */
const GENERATED_FOR = /omp-conductor project "([^"]+)"/;

/**
 * The project a generated file at `path` was rendered for, or `undefined`
 * when the file is absent, unreadable, or does not carry our marker. Any of
 * the three artefacts can identify its stem's owner, which is what lets a
 * write refuse to replace another project's files instead of silently doing
 * it (#720).
 */
export function generatedFor(path: string): string | undefined {
  try {
    return GENERATED_FOR.exec(readFileSync(path, "utf8"))?.[1];
  } catch {
    return undefined;
  }
}

/**
 * The first of `paths` that already exists and is not this project's own
 * artefact — another project's generated file, or something `setup graph`
 * never wrote — or `undefined` when every path is clear. The stem derives
 * from the project name, and two names can fold to one stem, so an existing
 * file's marker is checked before it is ever overwritten (#720).
 */
export function stagingConflict(
  p: ProjectConfig,
  paths: readonly string[],
): { path: string; owner: string | undefined } | undefined {
  for (const path of paths) {
    if (!existsSync(path)) continue;
    const owner = generatedFor(path);
    if (owner !== p.name) return { path, owner };
  }
  return undefined;
}

/** The refusal reason for a conflicting artefact, shared by the pre-consent
 *  check and the write backstop so both say the same thing. */
export function graphConflictMessage(conflict: { path: string; owner: string | undefined }): string {
  return (
    `${conflict.path} already exists and was ` +
    (conflict.owner === undefined
      ? "not generated by `setup graph` — refusing to overwrite it. Delete the file and re-run."
      : `generated for project "${conflict.owner}" — refusing to overwrite another project's reindex artefacts. Delete it and re-run.`)
  );
}

/**
 * The pre-#720 project-less artefact paths that still exist, in the order a
 * host that ran the old version has them. `setup graph` no longer writes or
 * installs these, so a host that upgrades keeps them — and their timer keeps
 * refreshing whichever project generated it last, forever.
 */
export function legacyReindexFiles(): string[] {
  return [
    join(stateDir(), `${REINDEX_UNIT}.sh`),
    join(stateDir(), `${REINDEX_UNIT}.service`),
    join(stateDir(), `${REINDEX_UNIT}.timer`),
  ].filter((f) => existsSync(f));
}

/** What to do with the legacy files, shared by the plan and the install
 *  warning so both say the same thing. */
export function legacyReindexNote(files: readonly string[]): string {
  return [
    `Legacy project-less reindex files still exist: ${files.join(", ")}.`,
    "`setup graph` no longer writes or installs them, so their timer refreshes",
    "whichever project generated it last, forever. Disable and delete them:",
    "  sudo systemctl disable --now cbm-reindex.timer",
    `  rm ${files.join(" ")}`,
  ].join("\n");
}

/** Where the upstream indexer lives, for an operator who has to go install it. */
const INDEXER_SOURCE = "https://github.com/DeusData/codebase-memory-mcp";

/**
 * The two things that must be true of the *host* before any index is useful,
 * neither of which conductor installs: the indexer has to be on PATH, and the
 * agent has to mount it as an MCP server or worker sessions get no graph tools
 * at all. Indexing without the mount produces a perfectly good database that
 * nothing can read — the failure this preflight exists to make visible.
 */
export interface GraphPrereqs {
  /** Resolved indexer path, or null when nothing on PATH answers to the name. */
  indexer: string | null;
  /** The agent's MCP server config, whether or not it exists yet. */
  mcpConfig: string;
  /** Whether that config already mounts the indexer for sessions. */
  mounted: boolean;
}

/** Reads the host. Split from {@link formatGraphSetup} so the plan stays pure. */
export function resolvePrereqs(home: string = homedir()): GraphPrereqs {
  const onPath = (process.env["PATH"] ?? "")
    .split(":")
    .filter((d) => d !== "")
    .map((d) => join(d, INDEXER))
    .find((c) => existsSync(c));

  const mcpConfig = join(home, ".omp", "agent", "mcp.json");
  let mounted = false;
  try {
    // Any mention of the binary counts as mounted. Parsing the whole schema to
    // decide would make this preflight fail on configs it does not understand,
    // and a false "not mounted" costs an operator a confusing duplicate entry.
    const raw = JSON.parse(readFileSync(mcpConfig, "utf8")) as Record<string, unknown>;
    const servers = (raw["mcpServers"] ?? raw) as Record<string, unknown>;
    mounted = Object.keys(servers).some((k) => k.includes(INDEXER));
  } catch {
    // No file, or unreadable: not mounted, and the plan says how to add it.
  }
  return { indexer: onPath ?? null, mcpConfig, mounted };
}

/** The `mcp.json` entry a fresh host needs, using the resolved path when known. */
export function mcpEntry(prereqs: GraphPrereqs): string {
  const command = prereqs.indexer ?? `/usr/local/bin/${INDEXER}`;
  return JSON.stringify({ [INDEXER]: { type: "stdio", command } }, null, 2);
}

/**
 * Default parent of every index-only clone, under the cache directory because
 * that is exactly what these are: derived data, disposable, re-creatable from a
 * clone URL. Deliberately *not* `~/projects/<org>` — that is where a human's own
 * checkouts live, and pointing a reindexer at one either destroys their
 * uncommitted work or indexes whatever branch they left checked out.
 *
 * `trackerRepo` supplies the org so a fleet's clones land together, which is
 * also the answer for the common case where the tracker and the code share one
 * GitHub organisation.
 */
export function defaultGraphRoot(trackerRepo: string): string {
  const org = trackerRepo.split("/")[0] ?? trackerRepo;
  return join(homedir(), ".cache", "conductor-graph", org);
}

/** One repo's clone under a chosen root. `~` is expanded here so a path an
 *  operator typed matches the absolute path the validator accepts. */
export function graphProjectPath(root: string, repoName: string): string {
  return join(expandHome(root.trim()), repoName);
}

/** A repo that has a graph, narrowed so callers need no further guard. */
export type GraphRepo = RepoTarget & { graphProject: string };

/** The project's repos that have a graph configured, in config order. */
export function graphRepos(p: ProjectConfig): GraphRepo[] {
  return Object.values(p.routing.repos).filter((r): r is GraphRepo => r.graphProject !== undefined);
}

/**
 * The project key the indexer derives from a path — the `project` argument
 * every code-graph tool takes, and the `<name>` in `<name>.db` under the
 * indexer's store. This is the mirror of the indexer's own
 * `cbm_project_name_from_path` (upstream `src/pipeline/fqn.c`):
 * validator-safe bytes survive, every other byte maps to `-` (non-ASCII
 * bytes to their two lowercase hex digits), runs of `-` and `.` collapse,
 * leading `-`/`.` and trailing `-` trim, an all-separator path falls back to
 * `root`, and a name over 200 bytes is bound with an FNV-1a suffix.
 *
 * A brief that named a wrong key would send a worker to a tool that answers
 * empty and reads as "no graph" — indistinguishable from silence. So this
 * matches the indexer byte for byte, and graph.test.ts pins it against names
 * taken from the live indexer store rather than against this function's own
 * output.
 */
export function graphProjectKey(graphProject: string): string {
  const bytes = new TextEncoder().encode(graphProject);
  let mapped = "";
  for (const b of bytes) {
    const safe =
      (b >= 0x61 && b <= 0x7a) || (b >= 0x41 && b <= 0x5a) || (b >= 0x30 && b <= 0x39) || b === 0x2e || b === 0x5f || b === 0x2d;
    if (safe) mapped += String.fromCharCode(b);
    else if (b >= 0x80) mapped += ((b >> 4) & 0xf).toString(16) + (b & 0xf).toString(16);
    else mapped += "-";
  }

  // Collapse consecutive dashes and dots (the validator also rejects "..").
  let collapsed = "";
  for (const ch of mapped) {
    const prev = collapsed[collapsed.length - 1];
    if ((ch === "-" && prev === "-") || (ch === "." && prev === ".")) continue;
    collapsed += ch;
  }

  // Trim leading dashes and dots (the validator rejects a leading dot) and
  // trailing dashes. A path that maps to nothing but separators is "root".
  let start = 0;
  while (start < collapsed.length && (collapsed[start] === "-" || collapsed[start] === ".")) start++;
  let end = collapsed.length;
  while (end > start && collapsed[end - 1] === "-") end--;
  const key = collapsed.slice(start, end);
  if (key === "") return "root";

  // Bound long names the way the indexer does (#624): first 191 bytes plus an
  // 8-hex FNV-1a of the full name, so two long paths that share a prefix but
  // differ later still map to distinct names. The mapped key is pure ASCII, so
  // per-character iteration is per-byte iteration.
  if (key.length > 200) {
    let hash = 2166136261;
    for (const ch of key) {
      hash ^= ch.charCodeAt(0);
      hash = Math.imul(hash, 16777619) >>> 0;
    }
    return key.slice(0, 191) + "-" + hash.toString(16).padStart(8, "0");
  }
  return key;
}

/**
 * The paragraph a worker's brief carries about its repo's graph: the exact
 * `project` key for a configured repo, or an explicit "no graph" statement for
 * an unconfigured one — never silence, because a worker that knows there is no
 * graph stops looking for one.
 *
 * The leading newline and the three-space indent are load-bearing: the
 * placeholder sits immediately before the next numbered item in
 * `briefs/worker.md`, so the hint reads as a continuation of the item above it
 * and never leaves a blank line behind.
 *
 * Every sentence here is defending against one specific failure. A worker that
 * derives the project name from its cwd gets an empty answer and concludes
 * there is no graph. A worker that indexes its own throwaway worktree writes a
 * dead index nobody reads — the 9.3 GB of stale worktree-keyed indexes this
 * fleet pruned. A worker that trusts the graph as current edits against a
 * snapshot that predates its own branch. All three end the same way — a
 * confident diff in the wrong place — so the wording says the quiet part out
 * loud rather than describing the tool.
 */
export function graphHint(repo: RepoTarget): string {
  const path = repo.graphProject;
  if (path === undefined) {
    return (
      "\n" +
      "   **This repo has no code graph configured.** Do not go looking for one:\n" +
      "   no index exists for it, so the graph tools answer empty whatever you\n" +
      "   pass — and indexing your own worktree would build a dead index nobody\n" +
      "   reads, not a shortcut. Grep is the tool for this run.\n"
    );
  }

  return (
    "\n" +
    "   **This repo has a code graph, and it was not built from your worktree.**\n" +
    "   Pass `project: \"" +
    graphProjectKey(path) +
    "\"` to every code-graph tool — the index the reindex timer\n" +
    "   builds for root_path `" +
    path +
    "`, shown under that name by\n" +
    "   `list_projects`. Never pass a path, and never pass your own cwd: that\n" +
    "   clone is what was indexed, your worktree has no index and never will,\n" +
    "   so a cwd-based lookup answers nothing and you lose the run to grep.\n" +
    "   Never run `index_repository` yourself — the refresh that builds this\n" +
    "   index is conductor's, and indexing your throwaway worktree writes a\n" +
    "   dead index nobody reads.\n" +
    "\n" +
    "   Read what it tells you as a snapshot of that clone's default branch at\n" +
    "   the last reindex: it does not contain your edits, and it can be hours\n" +
    "   behind the branch you are on. So orient with the graph, then read the\n" +
    "   real file in your worktree before you change it. If those tools are not\n" +
    "   mounted in this session, say so in your report and fall back to grep.\n"
  );
}

/**
 * `git clone` for one repo's index-only clone.
 *
 * `--single-branch` so the working tree can only ever hold the branch the graph
 * claims to describe, and the destination is quoted because the root is
 * operator-typed and a space in it would otherwise clone into two directories.
 */
export function cloneCommand(r: GraphRepo): string {
  return `git clone --single-branch --branch ${r.defaultBranch} ${r.cloneUrl} "${r.graphProject}"`;
}

/** The one-shot index command, as a human would run it to seed a clone. */
export function indexCommand(r: GraphRepo): string {
  return `${INDEXER} cli index_repository '{"repo_path": "${r.graphProject}"}'`;
}

/**
 * The refresh-and-reindex script both the timer and a human run.
 *
 * It fails loudly on purpose, and that is the one thing about it worth
 * protecting. A first draft of this — hand-written on the live host — used
 * `git fetch … || true; git pull --ff-only || true`, which meant a fetch that
 * failed for a week still indexed the stale tree and still exited 0: a green
 * timer serving a month-old graph, and workers orienting against code that no
 * longer exists. So: `set -euo pipefail`, no swallowed failures anywhere, and
 * the first broken repo takes the whole run non-zero where `systemctl status`
 * and `systemctl is-failed` will report it.
 *
 * `git reset --hard origin/<defaultBranch>` rather than a merge or a pull is
 * safe *because* of what these clones are — conductor's own, never edited by a
 * human — and it is the only refresh with no failure mode of its own: no
 * conflict, no divergence, no detached state to recover from. Each repo's own
 * configured branch is used, because a fleet with a `master` repo in it would
 * otherwise silently index nothing.
 */
export function reindexScript(p: ProjectConfig): string {
  const lines = [
    "#!/usr/bin/env bash",
    `# Refresh and reindex the code graphs for omp-conductor project "${p.name}".`,
    "#",
    "# Generated by \`omp-conductor setup graph\`. Regenerate it rather than editing:",
    "# the repo list, branches and paths all come from that project's config.json.",
    "#",
    "# Every clone below is conductor's own, index-only and never edited by a human,",
    "# which is what makes the hard reset safe. Do not point one at a checkout you",
    "# work in: the reset would destroy uncommitted work.",
    "#",
    "# Fails loud and stops at the first problem, deliberately. A refresh that",
    "# swallowed its errors would index a stale tree and still exit 0 — a green",
    "# timer serving a month-old graph is worse than no graph at all.",
    "set -euo pipefail",
    "",
  ];

  for (const r of graphRepos(p)) {
    lines.push(
      `# ${r.name} — ${r.cloneUrl} @ ${r.defaultBranch}`,
      `cd "${r.graphProject}"`,
      "git fetch --prune origin",
      `git reset --hard origin/${r.defaultBranch}`,
      indexCommand(r),
      "",
    );
  }

  return lines.join("\n");
}

/**
 * The service half. `Type=oneshot` with no `[Install]` section: it is started by
 * its timer, and a service enabled on its own would run once at boot and never
 * again, which looks exactly like a working install.
 */
export function reindexService(p: ProjectConfig, scriptPath = reindexScriptPath(p)): string {
  const home = homedir();
  const user = userInfo().username;
  return [
    "[Unit]",
    `Description=Reindex the code graphs omp-conductor project "${p.name}" hands its workers`,
    "After=network-online.target",
    "Wants=network-online.target",
    "",
    "[Service]",
    "Type=oneshot",
    `ExecStart=/bin/bash ${scriptPath}`,
    "# Pinned to the account that generated this, and it has to be the account the",
    "# fleet runs as. A systemd service defaults to root, and root is wrong three",
    "# ways at once here: the indexer would write its store under /root/.cache",
    "# where no worker session ever looks, a private clone would fetch with root's",
    "# SSH credentials rather than the fleet's, and every path below points into a",
    "# different account's home. All three fail silently — the timer goes green",
    "# and the graph a worker queries is simply never the graph this built.",
    `User=${user}`,
    "# Both of these are spelled out because systemd supplies neither usefully.",
    `# The indexer resolves its store from HOME (${join(home, ".cache", "codebase-memory-mcp")}),`,
    "# so an unset HOME would build a second index nobody queries; and systemd's",
    "# default PATH has no ~/.local/bin, while the indexer itself shells out to git.",
    `Environment=HOME=${home}`,
    `Environment=PATH=${["/.local/bin", "/.bun/bin"].map((d) => join(home, d)).join(":")}` +
      ":/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "# Indexing is CPU- and IO-heavy, and this host is also running the fleet whose",
    "# workers read the result.",
    "Nice=10",
    "IOSchedulingClass=idle",
    "# A wedged index must fail rather than hold its timer open indefinitely.",
    "TimeoutStartSec=1h",
    "",
  ].join("\n");
}

/**
 * The timer half — and the reason there is a timer at all.
 *
 * The graph server's own auto-watch lives inside a connected MCP session and
 * dies with it, and v0.9.0 ships no daemon. An ephemeral worker session
 * therefore keeps nothing fresh: whatever it mounts, it un-mounts minutes later.
 * So the refresh has to come from outside the fleet entirely, on a schedule
 * nothing in a run can influence.
 */
export function reindexTimer(p: ProjectConfig): string {
  return [
    "[Unit]",
    `Description=Periodic code-graph reindex for omp-conductor project "${p.name}"`,
    "",
    "[Timer]",
    "# Twenty minutes, because the measured cost is small and the cost of",
    "# staleness is not: refreshing four repos takes ~40s of CPU, which at this",
    "# interval is roughly 3% of one core, and the service runs at Nice=10 with",
    "# idle IO so it yields to the fleet. A nightly refresh would be cheaper and",
    "# much worse — a fleet merging several PRs a day would spend most of its",
    "# dispatches querying a graph that predates the code the worker was sent to",
    "# change, which is the one way this feature actively misleads. Lengthen it",
    "# for quiet repos; the brief has workers verify against the real file",
    "# regardless, so staleness degrades the graph rather than making it lie.",
    "OnBootSec=3min",
    "OnUnitActiveSec=20min",
    "# Persistent catches a host that was down; the jitter keeps every install",
    "# of this unit off the same second.",
    "Persistent=true",
    "RandomizedDelaySec=2m",
    "AccuracySec=1min",
    `Unit=${reindexUnitName(p)}.service`,
    "",
    "[Install]",
    "WantedBy=timers.target",
    "",
  ].join("\n");
}

/**
 * The privileged tail, and the only part of this feature that needs root.
 *
 * Split out deliberately. Running the whole CLI under `sudo` looks convenient
 * and is wrong: `loadConfig`, `stateDir`, `homedir` and `userInfo` would all
 * resolve as root, so the config would be missed or the wrong one, the script
 * would land in root's state directory, and the generated unit would bake
 * root's HOME with no `User=` — indexes written where no worker reads them.
 * So generation runs unprivileged as the fleet user, and only the copy into
 * the unit directory is elevated.
 */
export function installCommands(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR, from = stateDir()): string[] {
  const { service, timer } = unitPaths(p, from);
  return [
    `sudo install -m 0644 ${service} ${timer} ${unitDir}/`,
    `sudo systemctl daemon-reload && sudo systemctl enable --now ${reindexUnitName(p)}.timer`,
  ];
}

function block(title: string, body: string): string[] {
  return [`--- ${title} ---`, "", body.trimEnd(), ""];
}

/**
 * The whole plan as text, with nothing done. This is the `--print` mode of
 * `setup graph`, and it is a plan an operator can read, paste, or ignore —
 * including on a host where they are not root and the install would fail.
 */
export function formatGraphSetup(
  p: ProjectConfig,
  unitDir = SYSTEMD_UNIT_DIR,
  prereqs: GraphPrereqs = resolvePrereqs(),
): string {
  const repos = graphRepos(p);
  const missing = repos.filter((r) => !existsSync(r.graphProject));
  // Seeded with 0 so these are still widths when the caller ignored the exit-1
  // guard and asked for a plan for a project with no graph at all.
  const nameWidth = Math.max(0, ...repos.map((r) => r.name.length));
  const pathWidth = Math.max(0, ...repos.map((r) => r.graphProject.length));

  const lines = [
    `code-graph discovery for project "${p.name}"`,
    "",
    "Workers spend most of a run finding code rather than changing it. These",
    'indexes answer "who calls this" and "where is this defined" in one call, so',
    "the turns go into the work instead. Nothing below has been run.",
    "",
    `repos with a graph configured (${repos.length}):`,
  ];
  for (const r of repos) {
    // Padded so the (missing) markers line up: which clones do not exist yet is
    // the one thing an operator scans this list for.
    const marker = missing.includes(r) ? "  (missing)" : "";
    lines.push(`  ${r.name.padEnd(nameWidth)}  ${r.graphProject.padEnd(marker === "" ? 0 : pathWidth)}${marker}`);
  }

  // Before anything else, because both of these are host state conductor does
  // not own and neither failure is self-announcing: a missing binary surfaces
  // as command-not-found halfway down the plan, and a missing mount surfaces
  // as workers that never mention the graph and quietly grep instead.
  lines.push("", "0. host prerequisites", "");
  lines.push(
    prereqs.indexer === null
      ? `   [ ] ${INDEXER} is NOT on your PATH. Install it first — conductor never
       does, and never depends on it: ${INDEXER_SOURCE}`
      : `   [x] indexer: ${prereqs.indexer}`,
  );
  if (prereqs.mounted) {
    lines.push(`   [x] mounted for sessions in ${prereqs.mcpConfig}`);
  } else {
    lines.push(
      `   [ ] NOT mounted as an MCP server, so worker sessions have no graph`,
      `       tools and every index below would be unreadable. Add to`,
      `       ${prereqs.mcpConfig}:`,
      "",
      ...mcpEntry(prereqs)
        .split("\n")
        .map((l) => `       ${l}`),
    );
  }

  lines.push("", "1. create the clones that are missing", "");
  if (missing.length === 0) {
    lines.push("   every clone above already exists — nothing to create.");
  } else {
    lines.push(
      "   These are conductor's, not yours. Nothing human edits them, which is what",
      "   makes step 3's hard reset both safe and deterministic — so never point a",
      "   graphProject at a checkout you work in.",
      "",
    );
    for (const r of missing) lines.push(`   ${cloneCommand(r)}`);
  }

  lines.push(
    "",
    "2. index each one once now, so the first worker does not wait for the timer",
    "",
  );
  for (const r of repos) lines.push(`   ${indexCommand(r)}`);
  lines.push(
    "",
    "   Then check what a worker will see. Each root_path below must match a path",
    "   above exactly, and the name beside it is what a worker passes as `project`:",
    "",
    `   ${INDEXER} cli list_projects`,
    "",
    "3. keep them current",
    "",
  );

  const script = reindexScriptPath(p);
  const { service, timer } = unitPaths(p, stateDir());
  lines.push(
    `   \`omp-conductor setup graph\` writes these three files for you, all under`,
    `   ${stateDir()} — named for this project, so another project's files on the`,
    "   same host are never touched. Run it as the account the fleet runs as —",
    "   never under sudo, which would resolve the config, the state directory and",
    "   the unit's own User= as root and quietly build indexes no worker can read.",
    "",
    ...block(script, reindexScript(p)),
    ...block(service, reindexService(p, script)),
    ...block(timer, reindexTimer(p)),
    `   then install them, which is the only step that needs root:`,
    "",
    ...installCommands(p, unitDir).map((c) => `   ${c}`),
  );

  // An artefact another project (or nothing of ours) already owns at this
  // project's stem: the run would refuse rather than overwrite it, and the
  // plan must say so before the operator answers a consent prompt they will
  // not be asked (#720).
  const conflict = stagingConflict(p, [script, service, timer]);
  if (conflict !== undefined) {
    lines.push(
      "",
      `   NOTE: ${conflict.path} already exists and was ${
        conflict.owner === undefined ? "not generated by `setup graph`" : `generated for project "${conflict.owner}"`
      } —`,
      "   this run refuses to overwrite it. Delete the file and re-run.",
    );
  }

  // A host that ran the pre-#720 project-less version keeps its old files:
  // their timer refreshes whichever project generated it last, forever. The
  // plan names the remediation because it is host action this command must
  // not take for the operator.
  const legacy = legacyReindexFiles();
  if (legacy.length > 0) {
    lines.push("", "   NOTE: " + legacyReindexNote(legacy).replace(/\n/g, "\n   "));
  }

  return lines.join("\n");
}

/** One rendered artefact: where it lands and exactly what would be written. */
export interface GraphSetupFile {
  path: string;
  content: string;
}

/** The plan's three artefacts. */
export interface GraphSetupFiles {
  script: GraphSetupFile;
  service: GraphSetupFile;
  timer: GraphSetupFile;
}

/** What staging wrote, and the root-only steps it deliberately left. */
export interface GraphSetupWrite {
  written: string[];
  next: string;
}

/**
 * Everything `setup graph` would stage, rendered and nothing written: the
 * three files' paths and bytes, plus the `next` text naming the root-only
 * steps. The consent prompt prints this, and only the consent-gated step
 * turns it into files — so the prompt's "stages on confirm" is true of the
 * staged tree when it is printed, and a declined run leaves every staged
 * file byte-identical (#720, mirroring #510's deferral for `setup host`).
 */
export function planGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): GraphSetupFiles & { next: string } {
  const script = { path: reindexScriptPath(p), content: reindexScript(p) };
  // All three land in the state directory, which this account owns — so the
  // whole command runs unprivileged and there is no sudo path that could
  // resolve HOME, the config or the unit's User= as the wrong account.
  const service = { path: unitPaths(p, stateDir()).service, content: reindexService(p, script.path) };
  const timer = { path: unitPaths(p, stateDir()).timer, content: reindexTimer(p) };

  const missing = graphRepos(p).filter((r) => !existsSync(r.graphProject));
  const next = [
    "nothing has been installed, enabled or started — this command needs no root",
    `and takes none. The units are staged in ${stateDir()}.`,
    "",
    "to install them, which is the only privileged step:",
    "",
    ...installCommands(p, unitDir).map((c) => `  ${c}`),
    "",
    "then watch one real run before trusting the schedule (it takes minutes per repo):",
    "",
    `  sudo systemctl start ${reindexUnitName(p)}.service && systemctl status ${reindexUnitName(p)}.service`,
    ...(missing.length === 0
      ? []
      : [
          "",
          `first, though: ${missing.length} clone(s) do not exist yet, and the script fails`,
          "loudly rather than skipping them —",
          "",
          ...missing.map((r) => `  ${cloneCommand(r)}`),
        ]),
  ].join("\n");

  return { script, service, timer, next };
}

/**
 * Writes the script and both units, and returns what to do next.
 *
 * Deliberately stops there. Running `systemctl` would need root the wizard and
 * the CLI may not have, and a package that enables system timers behind an
 * operator's back is one you cannot audit by reading its output.
 *
 * Refuses an artefact that already exists and is not this project's own — a
 * collision between two names that fold to one stem is refused rather than
 * silently overwritten (#720).
 */
export function writeGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): GraphSetupWrite {
  const plan = planGraphSetup(p, unitDir);
  const conflict = stagingConflict(p, [plan.script.path, plan.service.path, plan.timer.path]);
  if (conflict !== undefined) throw new Error(graphConflictMessage(conflict));

  mkdirSync(dirname(plan.script.path), { recursive: true });
  writeFileSync(plan.script.path, plan.script.content);
  // Executable so an operator can run the refresh by hand before trusting a
  // timer with it; the unit calls bash explicitly either way.
  chmodSync(plan.script.path, 0o755);
  writeFileSync(plan.service.path, plan.service.content);
  writeFileSync(plan.timer.path, plan.timer.content);

  return { written: [plan.script.path, plan.service.path, plan.timer.path], next: plan.next };
}