omp-conductor 0.14.0 → 0.15.0

package/src/setup-install.ts

@@ -0,0 +1,320 @@
+/**
+ * The two executed install paths: the supervised daemon unit, and the code-graph
+ * timer.
+ *
+ * Both used to end at a printed list the operator retyped — `setup-host.ts`
+ * composed the exact `sudo` lines and showed them, and `graph-setup --write`
+ * staged its files and said it "never runs `systemctl` itself". Retyping is not
+ * a safety property: it is the same commands with a chance of a typo, and it is
+ * why a fleet sits half-installed. These run them, behind one confirm each.
+ *
+ * Why this module exists rather than the code living where its pieces do:
+ * `graph-health.ts` already imports `graph.ts`, so orchestration that verifies
+ * with `probeCodeGraph()` cannot sit in `graph.ts` without a cycle — and `cli.ts`
+ * is argument parsing, not sequencing. Both the CLI verbs and the wizard's tail
+ * call in here; `privileged.ts` stays the primitive underneath.
+ */
+
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { stateDir } from "./config.ts";
+import {
+  graphRepos,
+  formatGraphSetup,
+  mcpEntry,
+  reindexScriptPath,
+  resolvePrereqs,
+  REINDEX_UNIT,
+  unitPaths,
+  writeGraphSetup,
+  type GraphPrereqs,
+  type GraphRepo,
+} from "./graph.ts";
+import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
+import { runPrivileged, type PrivilegedDeps, type PrivilegedStep } from "./privileged.ts";
+import {
+  checkEscalation,
+  planHostRuntime,
+  totalConfiguredWorkers,
+  writeHostRuntime,
+  STAGED_SERVICE_NAME,
+  SYSTEMD_UNIT_DIR,
+  type EscalationDeps,
+} from "./setup-host.ts";
+import type { WizardUi } from "./wizard-ui.ts";
+import type { Caps, ProjectConfig } from "./types.ts";
+
+/**
+ * Every outcome a caller has to tell apart. `staged` is the non-Linux answer:
+ * the files are real and correct, only the `systemctl` half is impossible.
+ */
+export type InstallOutcome =
+  | { kind: "installed"; wrote: readonly string[] }
+  | { kind: "staged"; wrote: readonly string[]; reason: string }
+  | { kind: "declined"; wrote: readonly string[] }
+  | { kind: "refused"; reason: string }
+  | { kind: "failed"; reason: string };
+
+export interface InstallDeps {
+  privileged?: PrivilegedDeps;
+  escalation?: EscalationDeps;
+  /** `"linux"` gates the systemd half. Injectable so the refusal is testable. */
+  platform?: () => string;
+  unitDir?: string;
+}
+
+/**
+ * `systemctl` exists only on Linux, and staging is still worth doing everywhere:
+ * a macOS operator reading the plan wants the rendered unit on disk to copy to
+ * the box that will run it. So this is checked *after* the files are written.
+ */
+function linuxOnly(deps: InstallDeps): string | undefined {
+  return (deps.platform ?? platform)() === "linux"
+    ? undefined
+    : "systemd install is Linux-only; staged files are at";
+}
+
+/**
+ * Install the supervised daemon unit: re-render, stage, then run the four steps
+ * `planHostRuntime` used to only print.
+ */
+export async function runHostInstall(
+  project: ProjectConfig,
+  caps: Caps,
+  telegramStateDir: string,
+  ui: WizardUi,
+  deps: InstallDeps = {},
+): Promise<InstallOutcome> {
+  const verdict = checkEscalation("setup host", deps.escalation);
+  if (verdict.kind === "refuse") {
+    ui.notify(verdict.message, "error");
+    return { kind: "refused", reason: verdict.message };
+  }
+
+  const plan = planHostRuntime(project, caps, telegramStateDir, undefined, hostInstallWorkers(caps));
+  const wrote = writeHostRuntime(plan);
+  const unitDir = deps.unitDir ?? SYSTEMD_UNIT_DIR;
+  const installed = join(unitDir, STAGED_SERVICE_NAME);
+
+  const blocked = linuxOnly(deps);
+  if (blocked !== undefined) {
+    ui.notify(`${blocked} ${plan.service.path}`, "warning");
+    return { kind: "staged", wrote, reason: `${blocked} ${plan.service.path}` };
+  }
+
+  // argv, not shell: `installCommands` renders `sudo …` strings for humans to
+  // read, and re-parsing those into an argv is how a path with a space becomes
+  // two arguments. The steps are built from the same values instead.
+  const steps: PrivilegedStep[] = [
+    { title: `install ${STAGED_SERVICE_NAME}`, argv: ["install", "-m", "0644", plan.service.path, installed] },
+    { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+    { title: `enable ${STAGED_SERVICE_NAME}`, argv: ["systemctl", "enable", STAGED_SERVICE_NAME] },
+    { title: `restart ${STAGED_SERVICE_NAME}`, argv: ["systemctl", "restart", STAGED_SERVICE_NAME] },
+  ];
+
+  const outcome = await runPrivileged(steps, ui, {
+    ...(deps.privileged === undefined ? {} : { deps: deps.privileged }),
+    title: "Install and start the supervised daemon?",
+    preamble: [
+      `Installs ${plan.service.path} as ${installed}, then enables and restarts it.`,
+      "The unit runs as the account that staged it; nothing here changes that.",
+    ],
+  });
+  if (outcome.kind === "declined") return { kind: "declined", wrote };
+  if (outcome.kind === "failed") {
+    return { kind: "failed", reason: `${outcome.step.title} exited ${outcome.exitCode}` };
+  }
+  ui.notify(`Installed and started ${STAGED_SERVICE_NAME}.`, "info");
+  return { kind: "installed", wrote };
+}
+
+/** Fleet-wide worker sum when config is loadable; otherwise this project's caps. */
+function hostInstallWorkers(caps: Caps): number {
+  try {
+    return totalConfiguredWorkers();
+  } catch {
+    return caps.maxConcurrentWorkers;
+  }
+}
+
+export interface GraphInstallOptions extends InstallDeps {
+  /**
+   * Skip the seeding step. The timer is still installed and enabled, and the
+   * graph is plainly unusable until its first scheduled run finishes. Never
+   * skips the prerequisite or clone steps: those are what make the installed
+   * unit runnable at all.
+   */
+  noSeed?: boolean;
+  /** Print the plan and change nothing — today's `graph-setup` behaviour. */
+  print?: boolean;
+  /** Injected so the prerequisite gate is testable without touching PATH. */
+  prereqs?: GraphPrereqs;
+  /** Injected so verification is deterministic without a live indexer. */
+  probe?: (project: ProjectConfig) => Promise<CodeGraphHealth>;
+}
+
+/**
+ * The code-graph install, end to end.
+ *
+ * Staging and enabling alone installs a service that fails on every run: the
+ * generated script runs under `set -euo pipefail` and `cd "<graphProject>"` as
+ * its first act per repo, so a missing clone is a `cd` failure at 03:00 rather
+ * than a graph. That is why `writeGraphSetup` already refused to call the old
+ * install a finished job. So: prerequisites, then clones, then install, then
+ * seed and verify — one preview, one confirm.
+ */
+export async function runGraphInstall(
+  project: ProjectConfig,
+  ui: WizardUi,
+  options: GraphInstallOptions = {},
+): Promise<InstallOutcome> {
+  const repos = graphRepos(project);
+  if (repos.length === 0) {
+    const reason = `no repo in ${project.name} has graphProject — nothing to install`;
+    ui.notify(reason, "error");
+    return { kind: "refused", reason };
+  }
+
+  const prereqs = options.prereqs ?? resolvePrereqs();
+
+  // `--print` is today's `graph-setup`: read-only, writes nothing, runs nothing.
+  // It comes first — before the escalation guard and before the prerequisite
+  // refusal — because the host that most needs the plan is exactly the fresh one
+  // missing the indexer, and refusing there would withhold the remediation the
+  // operator ran the command to get. `formatGraphSetup` is that renderer, and it
+  // already reports the prerequisites as step 0.
+  if (options.print === true) {
+    ui.notify(formatGraphSetup(project, options.unitDir ?? SYSTEMD_UNIT_DIR, prereqs), "info");
+    return { kind: "staged", wrote: [], reason: "print-only" };
+  }
+
+  const verdict = checkEscalation("setup graph", options.escalation);
+  if (verdict.kind === "refuse") {
+    ui.notify(verdict.message, "error");
+    return { kind: "refused", reason: verdict.message };
+  }
+
+  // 1. Prerequisites. With no indexer on PATH every timer run fails, and with no
+  //    MCP entry no worker can read what it indexed — so this stops before
+  //    installing anything rather than enabling a timer that cannot work.
+  const missing = prerequisiteProblem(prereqs);
+  if (missing !== undefined) {
+    ui.notify([missing, "", mcpEntry(prereqs)].join("\n"), "error");
+    return { kind: "refused", reason: missing };
+  }
+
+  const staged = writeGraphSetup(project, options.unitDir ?? SYSTEMD_UNIT_DIR);
+  const absent = repos.filter((r) => !existsSync(r.graphProject));
+
+  // 2. Missing clones, as the operator. A root-owned index-only clone under the
+  //    fleet user's cache is exactly the failure the escalation guard exists to
+  //    prevent — but it belongs in the same plan under the same confirm.
+  const clones: PrivilegedStep[] = absent.map((r) => ({
+    title: `clone ${r.name} for indexing (as you, not root)`,
+    argv: ["git", "clone", "--single-branch", "--branch", r.defaultBranch, r.cloneUrl, r.graphProject],
+    unprivileged: true,
+  }));
+
+  const blocked = linuxOnly(options);
+  const { service, timer } = unitPaths(options.unitDir ?? SYSTEMD_UNIT_DIR);
+  const from = unitPaths(stateDir());
+  // 3. Install and enable, privileged. 4. Seed, in the SAME batch: the contract is
+  //    one preview and one confirm, and a second confirm here also invented a
+  //    third outcome — a declined seed — that neither the caller nor the
+  //    verification below could interpret.
+  const seed: PrivilegedStep[] =
+    options.noSeed === true
+      ? []
+      : [{ title: `seed the indexes (runs ${REINDEX_UNIT}.service once, minutes per repo)`, argv: ["systemctl", "start", `${REINDEX_UNIT}.service`] }];
+  const install: PrivilegedStep[] =
+    blocked === undefined
+      ? [
+          { title: "install the reindex unit and timer", argv: ["install", "-m", "0644", from.service, from.timer, join(options.unitDir ?? SYSTEMD_UNIT_DIR, "")] },
+          { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+          { title: `enable ${REINDEX_UNIT}.timer`, argv: ["systemctl", "enable", "--now", `${REINDEX_UNIT}.timer`] },
+          ...seed,
+        ]
+      : [];
+
+  if (blocked !== undefined) {
+    ui.notify(`${blocked} ${service} and ${timer}`, "warning");
+    return { kind: "staged", wrote: staged.written, reason: `${blocked} ${service}` };
+  }
+
+  if (blocked !== undefined) {
+    ui.notify(`${blocked} ${service} and ${timer}`, "warning");
+    return { kind: "staged", wrote: staged.written, reason: `${blocked} ${service}` };
+  }
+
+  const outcome = await runPrivileged([...clones, ...install], ui, {
+    ...(options.privileged === undefined ? {} : { deps: options.privileged }),
+    title: "Clone, install and enable the code-graph timer?",
+    preamble: [
+      `Staged: ${staged.written.join(", ")}.`,
+      ...(clones.length === 0
+        ? ["Every indexed clone already exists."]
+        : [`${clones.length} clone(s) run as you; the unit install needs root.`]),
+      `Indexer: ${prereqs.indexer ?? "on PATH"}.`,
+    ],
+  });
+  if (outcome.kind === "declined") return { kind: "declined", wrote: staged.written };
+  if (outcome.kind === "failed") {
+    return { kind: "failed", reason: `${outcome.step.title} exited ${outcome.exitCode}` };
+  }
+
+  // Verify. `--no-seed` has nothing to verify yet, and saying so is the honest
+  // answer: an unseeded graph is not usable until the timer first fires.
+  if (options.noSeed === true) {
+    ui.notify(
+      `Timer enabled; skipped the seeding run. The graph is NOT usable until ${REINDEX_UNIT}.timer first fires.`,
+      "warning",
+    );
+    return { kind: "installed", wrote: staged.written };
+  }
+
+  const health = await (options.probe ?? probeCodeGraph)(project);
+  const unhealthy = unverifiedRepos(health);
+  if (unhealthy.length > 0) {
+    // Staged but not trusted. Reporting success here is how an operator learns
+    // months later that no worker ever read an index.
+    ui.notify(
+      [`Installed, but ${unhealthy.length} repo(s) did not verify: ${unhealthy.join(", ")}.`, "", staged.next].join("\n"),
+      "error",
+    );
+    return { kind: "failed", reason: `unverified: ${unhealthy.join(", ")}` };
+  }
+  ui.notify(`Code graph installed and verified for ${repos.map((r) => r.name).join(", ")}.`, "info");
+  return { kind: "installed", wrote: staged.written };
+}
+
+/** The two prerequisites that make an enabled timer meaningful, or `undefined`. */
+function prerequisiteProblem(prereqs: GraphPrereqs): string | undefined {
+  if (prereqs.indexer === null) {
+    return "codebase-memory-mcp is not on PATH — every timer run would fail, so nothing was installed.";
+  }
+  if (!prereqs.mounted) {
+    return "no codebase-memory MCP entry — no worker could read the indexes, so nothing was installed.";
+  }
+  return undefined;
+}
+
+/**
+ * Repos whose index the probe could not vouch for: a missing clone, or an
+ * indexed project path that never appeared in `list_projects`. Either one means
+ * staged-but-not-trusted, which must not be reported as success.
+ */
+function unverifiedRepos(health: CodeGraphHealth): string[] {
+  if (!health.configured) return [];
+  return health.repos.filter((r) => r.clone !== "present" || r.index !== "present").map((r) => r.name);
+}
+
+/** The repos `setup graph` would act on, for a caller deciding whether to offer it. */
+export function graphInstallable(project: ProjectConfig): GraphRepo[] {
+  return graphRepos(project);
+}
+
+/** Where the reindex script lands, for the wizard's tail to name. */
+export function reindexScriptLocation(): string {
+  return reindexScriptPath();
+}