mesh-catalog/modules/lab/tools/index.ts

// lab's tools — the lab, as the mesh asks for it (novox/hq ADR 0172). They run on the machine the
// lab is assigned to, and only there: a bed raises virtual machines on that machine's virtualisation.

import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
import { installPlan, listRuns, NPM_REPOSITORIES, readStatus, REPOSITORIES, running, start, stop, tail } from "./runs.js";

export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
  const work = env.MESH_LAB_WORK ?? "/var/lib/mesh-lab-runs";
  // The forge is an operator's setting, which reaches a file and never a bundle's words (novox/hq
  // ADR 0192): read from the env-file the mesh fills, at each call, so a changed setting is used
  // without restarting the runtime. MESH_LAB_FORGE itself still wins, for a hand-run instance.
  const forgeOf = (): string => (env.MESH_LAB_FORGE ?? wordIn(env.MESH_LAB_ENV_FILE, "MESH_LAB_FORGE")).replace(/\/+$/, "");
  return [
    {
      name: "lab_check",
      description: "Whether this machine can run the lab's beds: the lab's own check, against the forge's main branch.",
      input: {},
      run: async () => {
        const forge = forgeOf();
        if (!forge) return { ok: false, output: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
        const dir = `${work}/check`;
        spawnSync("rm", ["-rf", dir]);
        const clone = spawnSync("git", ["clone", "--quiet", "--depth", "1", `${forge}/novox/mesh-lab.git`, dir], { encoding: "utf8" });
        if (clone.status !== 0) return { ok: false, output: clone.stderr };
        spawnSync("npm", ["ci", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir, encoding: "utf8" });
        const check = spawnSync("node", ["--experimental-strip-types", "src/cli.ts", "check"], { cwd: dir, encoding: "utf8" });
        // **And what a run would check out and install, before a run finds out** (novox/hq issue 624): every
        // repository it clones answers on the forge, and every one it installs has a lock file where the run
        // installs from.
        const problems = setupProblems(forge, `${work}/check-setup`);
        const output = [`${check.stdout}${check.stderr}`.trim(), ...problems].filter(Boolean).join("\n");
        return { ok: check.status === 0 && problems.length === 0, output };
      },
    },
    {
      name: "lab_run",
      description:
        "Run the lab's beds against branches on the forge: fresh checkouts of every repository the lab builds, " +
        "side by side, then the suite on the named test files. Answers at once with the run's id; lab_status " +
        "and lab_log follow it. One run at a time.",
      input: {
        tests: { type: "string", description: "the bed test files, comma-separated, relative to mesh-lab (e.g. test/integration/mesh.test.ts)" },
        refs: {
          type: "string",
          description: `a JSON object of repository to branch, for any of ${REPOSITORIES.join(", ")}; the rest run main`,
        },
      },
      run: async (args) => {
        const forge = forgeOf();
        if (!forge) return { started: false, reason: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
        const tests = String(args.tests ?? "").split(",").map((s) => s.trim()).filter(Boolean);
        if (tests.length === 0) return { started: false, reason: "name at least one bed test file" };
        let refs: Record<string, string> = {};
        if (args.refs) {
          try {
            refs = JSON.parse(String(args.refs)) as Record<string, string>;
          } catch {
            return { started: false, reason: "refs is not a JSON object of repository to branch" };
          }
        }
        const stranger = Object.keys(refs).filter((r) => !REPOSITORIES.includes(r));
        if (stranger.length > 0) return { started: false, reason: `the lab does not build ${stranger.join(", ")}` };
        const busy = running(work);
        if (busy) return { started: false, reason: `${busy.id} is still ${busy.state}; one run at a time`, running: busy };
        return { started: true, run: start(work, forge, tests, refs) };
      },
    },
    {
      name: "lab_status",
      description: "A run's state, the commits it tested and how it ended — or every run, newest first, when no id is given.",
      input: { id: { type: "string", description: "the run's id (optional)" } },
      run: async (args) => {
        if (args.id) return readStatus(work, String(args.id)) ?? { found: false, id: String(args.id) };
        return { runs: listRuns(work).slice(0, 10) };
      },
    },
    {
      name: "lab_log",
      description: "The last lines of a run's log.",
      input: {
        id: { type: "string", description: "the run's id" },
        lines: { type: "number", description: "how many lines from the end (default 200)" },
      },
      run: async (args) => ({ id: String(args.id), log: tail(work, String(args.id), Number(args.lines ?? 200)) }),
    },
    {
      name: "lab_stop",
      description: "Stop a run and everything it started.",
      input: { id: { type: "string", description: "the run's id" } },
      run: async (args) => stop(work, String(args.id)) ?? { found: false, id: String(args.id) },
    },
  ];
}

/**
 * What would stop a run at its setup, in sentences: a repository the run clones that the forge does not
 * answer for, and a checkout it installs with nothing installable (installPlan). Empty when a run's setup
 * would go through.
 */
export function setupProblems(forge: string, dir: string): string[] {
  const problems: string[] = [];
  spawnSync("rm", ["-rf", dir]);
  for (const repo of REPOSITORIES) {
    const url = `${forge}/novox/${repo}.git`;
    const remote = spawnSync("git", ["ls-remote", "--heads", url, "main"], { encoding: "utf8" });
    if (remote.status !== 0 || !remote.stdout.includes("refs/heads/main")) {
      problems.push(`a run checks out ${repo}, and ${url} answers no main branch`);
      continue;
    }
    if (!NPM_REPOSITORIES.includes(repo)) continue;
    const at = `${dir}/${repo}`;
    const clone = spawnSync("git", ["clone", "--quiet", "--depth", "1", url, at], { encoding: "utf8" });
    if (clone.status !== 0) {
      problems.push(`${repo} could not be cloned from ${url}: ${clone.stderr.trim()}`);
      continue;
    }
    const plan = installPlan(at);
    for (const d of plan.unlocked) problems.push(`${repo}: ${d.slice(at.length) || "/"} has a package.json and no package-lock.json, so a run's npm ci cannot install it`);
    if (plan.install.length === 0 && plan.unlocked.length === 0) {
      problems.push(`${repo}: no package-lock.json at its root or one directory down, so a run installs nothing of it`);
    }
  }
  spawnSync("rm", ["-rf", dir]);
  return problems;
}

/** One word from an env-file (`KEY=value` lines), or "" when the file or the word is absent. */
export function wordIn(file: string | undefined, word: string): string {
  if (!file) return "";
  let text: string;
  try {
    text = readFileSync(file, "utf8");
  } catch {
    return "";
  }
  for (const line of text.split("\n")) {
    const at = line.indexOf("=");
    if (at > 0 && line.slice(0, at).trim() === word) return line.slice(at + 1).trim();
  }
  return "";
}

registerModuleTools("lab", (env) => getLabTools(env));