@mnaimfaizy/agent-kit 0.0.0-stage → 1.0.0-beta.1

package/src/cli.mjs

@@ -0,0 +1,229 @@
+// Argument parsing and dispatch. Exit codes: 0 ok, 1 a check failed (or a
+// warning under --strict, or the tag or the change was refused), 2 usage
+// error (including a missing answer when there is no terminal to ask on).
+
+import { parseArgs } from "node:util";
+import { formatReport, runDoctor } from "./doctor.mjs";
+import { REPO_PATTERN, sanitizeLine } from "./checks/result.mjs";
+import { systemRunner } from "./exec.mjs";
+import { askYesNo } from "./prompt.mjs";
+import { CLI_VERSION, isReleaseTag } from "./tags.mjs";
+import { runInit } from "./init.mjs";
+import { runUpgrade } from "./upgrade.mjs";
+
+export const VERSION = CLI_VERSION;
+
+const USAGE = `Usage: agent-kit <command> [options]
+
+Commands:
+  init       Adopt Agent-kit from a tag: copy the Kit-owned paths, write a
+             Caller per flow with your answers filled in, the Threat pack
+             skeleton and .github/dependabot.yml, then print the GitHub-side
+             steps as gh commands. Local files only.
+  doctor     Read-only checks of this repository against the Agent-kit tag
+             its Callers pin. Never changes anything.
+  upgrade    Move this repository to another Agent-kit tag: replace the
+             Kit-owned paths, rewrite the uses: pins, print the examples/
+             diff, then run doctor's file and pin checks. Local files only.
+
+Options for doctor:
+  --ci            Check only Kit-owned paths and uses: pins (no gh needed).
+                  Used automatically when gh has no admin login on the repo.
+  --strict        Treat warnings as failures.
+  --repo <o/r>    The GitHub repository to check (default: gh's choice for
+                  the current directory).
+
+Options for init (each one is asked for when missing, on a terminal):
+  --tag <vX>              The Agent-kit tag to adopt.
+  --flows <list>          pipeline, audit, or both (comma-separated).
+  --actors <logins>       GitHub logins allowed to trigger runs.
+  --default-branch <b>    Default branch (default: origin's HEAD, else main).
+  --verify <commands>     verify_commands for implement (pipeline). In a
+                          prompt, \\n separates commands.
+  --preset <name|none>    Inline examples/setup-presets/<name>.sh as
+                          setup_commands (pipeline; default none).
+  --threat-pack-dir <d>   Where the Threat pack goes (audit; default .security).
+  --yes                   Ask nothing; every answer comes from flags.
+  --force                 Overwrite existing Callers, Threat pack files and
+                          Kit-owned paths (use upgrade to change tags).
+
+Options for upgrade:
+  --tag <vY>      The Agent-kit tag to move to (asked for when missing).
+  --from <vX>     The tag you are leaving, when the pins already name <vY>
+                  (after a Dependabot bump): deletes paths only <vX> listed
+                  and prints the examples/ diff.
+  --yes           Do not ask before changing files.
+  --force         Replace Kit-owned paths even when they have uncommitted
+                  changes (those changes are lost).
+
+  -h, --help      Show this help.
+  -v, --version   Show the version.`;
+
+const COMMAND_OPTIONS = {
+  doctor: ["ci", "strict", "repo"],
+  init: [
+    "tag",
+    "flows",
+    "actors",
+    "default-branch",
+    "verify",
+    "preset",
+    "threat-pack-dir",
+    "yes",
+    "force",
+  ],
+  upgrade: ["tag", "from", "yes", "force"],
+};
+
+/**
+ * @param {string[]} argv
+ * @param {{
+ *   cwd: string,
+ *   stdout: (s: string) => void,
+ *   stderr: (s: string) => void,
+ *   runner?: import("./exec.mjs").Runner,
+ *   openTag?: Function,
+ *   openRepo?: Function,
+ *   prompt?: ((question: string) => Promise<string>) | null,
+ * }} io  `prompt` is null (or absent) when there is no terminal to ask on.
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, io) {
+  const { cwd, runner = systemRunner, openTag, openRepo, prompt = null } = io;
+  // Anything printed can echo arguments or file contents: sanitize every line.
+  const clean = (text) => String(text).split("\n").map(sanitizeLine).join("\n");
+  const stdout = (text) => io.stdout(clean(text));
+  const stderr = (text) => io.stderr(clean(text));
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      strict: true,
+      options: {
+        ci: { type: "boolean" },
+        strict: { type: "boolean" },
+        repo: { type: "string" },
+        tag: { type: "string" },
+        from: { type: "string" },
+        flows: { type: "string" },
+        actors: { type: "string" },
+        "default-branch": { type: "string" },
+        verify: { type: "string" },
+        preset: { type: "string" },
+        "threat-pack-dir": { type: "string" },
+        yes: { type: "boolean", short: "y" },
+        force: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+    });
+  } catch (err) {
+    stderr(`${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+  const { values, positionals } = parsed;
+  if (values.version) {
+    stdout(VERSION);
+    return 0;
+  }
+  const [command, ...rest] = positionals;
+  if (values.help || !command) {
+    (command || values.help ? stdout : stderr)(USAGE);
+    return values.help ? 0 : 2;
+  }
+  if (!(command in COMMAND_OPTIONS)) {
+    stderr(`Unknown command: ${command}\n\n${USAGE}`);
+    return 2;
+  }
+  if (rest.length) {
+    stderr(`${command} takes no arguments, got: ${rest.join(" ")}`);
+    return 2;
+  }
+  const foreign = Object.keys(values).filter(
+    (k) => k !== "help" && k !== "version" && !COMMAND_OPTIONS[command].includes(k),
+  );
+  if (foreign.length) {
+    stderr(`${command} does not take ${foreign.map((k) => `--${k}`).join(", ")}\n\n${USAGE}`);
+    return 2;
+  }
+
+  if (command === "init") {
+    stdout(`agent-kit init ${VERSION}`);
+    return runInit({
+      cwd,
+      runner,
+      flags: {
+        tag: values.tag,
+        flows: values.flows,
+        actors: values.actors,
+        defaultBranch: values["default-branch"],
+        verify: values.verify,
+        preset: values.preset,
+        threatPackDir: values["threat-pack-dir"],
+      },
+      force: Boolean(values.force),
+      yes: Boolean(values.yes),
+      prompt,
+      confirm: prompt ? (q) => askYesNo(prompt, q) : null,
+      out: stdout,
+      err: stderr,
+      ...(openTag ? { openTag } : {}),
+    });
+  }
+  if (command === "upgrade") {
+    return upgrade(values, { cwd, runner, openRepo, prompt, stdout, stderr });
+  }
+
+  if (values.repo !== undefined && !REPO_PATTERN.test(values.repo)) {
+    stderr(`--repo must be owner/name, got: ${JSON.stringify(values.repo)}`);
+    return 2;
+  }
+  const report = runDoctor({
+    cwd,
+    runner,
+    ci: Boolean(values.ci),
+    strict: Boolean(values.strict),
+    repo: values.repo,
+    ...(openTag ? { openTag } : {}),
+  });
+  stdout(formatReport(report, { version: VERSION }));
+  return report.exitCode;
+}
+
+async function upgrade(values, { cwd, runner, openRepo, prompt, stdout, stderr }) {
+  if (!prompt) {
+    // No terminal: every answer must come from a flag.
+    const needed = [];
+    if (values.tag === undefined) needed.push("--tag <vY>");
+    if (!values.yes) needed.push("--yes");
+    if (needed.length) {
+      stderr(`agent-kit upgrade: there is no terminal to ask on, so pass ${needed.join(" and ")}.`);
+      return 2;
+    }
+  }
+  let tag = values.tag;
+  if (tag === undefined) tag = await prompt("Agent-kit tag to upgrade to (for example v1.0.0): ");
+  if (values.from !== undefined && !isReleaseTag(values.from)) {
+    stderr(`--from must be a Release-line tag, got: ${JSON.stringify(values.from)}`);
+    return 2;
+  }
+  if (!isReleaseTag(tag)) {
+    stderr(
+      `--tag must be a Release-line tag (vX.Y.Z or vX.Y.Z-stage.N), got: ${JSON.stringify(tag)}`,
+    );
+    return 2;
+  }
+  stdout(`agent-kit upgrade ${VERSION}`);
+  return runUpgrade({
+    cwd,
+    runner,
+    tag,
+    from: values.from,
+    force: Boolean(values.force),
+    yes: Boolean(values.yes),
+    confirm: prompt ? (q) => askYesNo(prompt, q) : null,
+    out: stdout,
+    ...(openRepo ? { openRepo } : {}),
+  });
+}

package/src/doctor.mjs

@@ -0,0 +1,405 @@
+// `agent-kit doctor`: read-only checks of a Consumer repository against the
+// Agent-kit tag its Callers pin. Local mode (an admin `gh` login) runs every
+// check; CI mode runs only the file and pin checks and lists the rest as
+// skipped. A skipped check is never reported as passed.
+
+import { readWorkflows } from "./callers.mjs";
+import { checkClaudeApp } from "./checks/claude-app.mjs";
+import { checkKitOwnedTrees } from "./checks/kit-owned-trees.mjs";
+import { checkLabels } from "./checks/labels.mjs";
+import { checkPins } from "./checks/pins.mjs";
+import { result, sanitizeLine } from "./checks/result.mjs";
+import {
+  checkCreationRule,
+  checkPersonalTagPush,
+  checkTagRuleset,
+  checkUpdateRule,
+  loadRulesets,
+} from "./checks/rulesets.mjs";
+import {
+  checkSecrets,
+  checkVariables,
+  deriveRequirements,
+  deriveVariables,
+} from "./checks/secrets-and-variables.mjs";
+import { firstLine } from "./exec.mjs";
+import { createGitHub } from "./github.mjs";
+import { openKitTag, PreManifestTagError, serverFromEnv } from "./kit-tag.mjs";
+
+/**
+ * The GitHub server the pins resolve on: the repository's host in a local
+ * run, GITHUB_SERVER_URL in GitHub Actions (set on GitHub Enterprise Server
+ * too), else github.com.
+ */
+function serverFor(info, env) {
+  if (info?.host) return `https://${info.host}`;
+  return serverFromEnv(env);
+}
+
+/** The checks that need a `gh` login with admin on the repository. */
+export const LOCAL_ONLY_CHECKS = [
+  ["secrets", "Secrets the Callers pass are set"],
+  ["variables", "Repository variables the Callers read are set"],
+  ["trigger-labels", "Trigger labels exist"],
+  ["claude-app", "Claude GitHub App installed"],
+  ["ruleset-update", "Default branch has an update rule"],
+  ["ruleset-creation", "Release branches have a creation rule"],
+  ["ruleset-tags", "Release tags have a v* tag ruleset"],
+  ["release-tag-push", "Release tags can be pushed under the tag ruleset"],
+];
+
+const skipAll = (ids, reason) => ids.map(([id, title]) => result(id, title, "skip", reason));
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   runner: import("./exec.mjs").Runner,
+ *   ci?: boolean,
+ *   strict?: boolean,
+ *   repo?: string,
+ *   openTag?: typeof openKitTag,
+ *   env?: NodeJS.ProcessEnv,
+ * }} opts
+ * @returns {{ mode: "local" | "ci", modeReason: string | null, repo: string | null, tag: string | null, results: object[], refusal: string | null, exitCode: number }}
+ */
+export function runDoctor({
+  cwd,
+  runner,
+  ci = false,
+  strict = false,
+  repo: repoArg,
+  openTag = openKitTag,
+  env = process.env,
+}) {
+  const results = [];
+  let mode = ci ? "ci" : "local";
+  let modeReason = ci ? "--ci" : null;
+
+  // Which repository, and may this login read its settings?
+  let info = null;
+  if (!ci) {
+    const github = createGitHub(runner, { cwd });
+    try {
+      info = repoInfo(github, repoArg);
+      if (!info.admin) {
+        mode = "ci";
+        modeReason = `your gh login is not an admin on ${info.repo}`;
+      }
+    } catch (err) {
+      mode = "ci";
+      modeReason = `gh could not read the repository (${firstLine(err.message)})`;
+    }
+  }
+
+  let root = cwd;
+  const top = runner("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+  if (top.status === 0) root = top.stdout.trim();
+  else {
+    results.push(result("pins", "uses: pins agree", "fail", `${cwd} is not a git repository.`));
+    return finish({
+      mode,
+      modeReason,
+      repo: info?.repo ?? null,
+      tag: null,
+      results,
+      refusal: null,
+      strict,
+    });
+  }
+
+  let workflows;
+  try {
+    workflows = readWorkflows(root);
+  } catch (err) {
+    // Nothing else can run without the Callers: report it, never crash.
+    results.push(result("pins", "uses: pins agree", "fail", firstLine(err?.message ?? err)));
+    return finish({
+      mode,
+      modeReason,
+      repo: info?.repo ?? null,
+      tag: null,
+      results,
+      refusal: null,
+      strict,
+    });
+  }
+  const { files, callers } = workflows;
+  const pins = checkPins(files);
+  results.push(pins.result);
+
+  let snapshot = null;
+  let refusal = null;
+  if (pins.tag) {
+    try {
+      // Read-only: accept any safe manifest path, so an older CLI can check a
+      // newer tag. Code that deletes paths keeps the strict shapes.
+      snapshot = openTag({
+        runner,
+        repo: pins.repo,
+        tag: pins.tag,
+        serverUrl: serverFor(info, env),
+        forDeletion: false,
+      });
+    } catch (err) {
+      if (err instanceof PreManifestTagError) refusal = err.message;
+      else
+        results.push(
+          result("kit-owned-trees", "Kit-owned paths match the pinned tag", "fail", err.message),
+        );
+    }
+  } else {
+    results.push(
+      result(
+        "kit-owned-trees",
+        "Kit-owned paths match the pinned tag",
+        "skip",
+        "No single pinned tag to compare against.",
+      ),
+    );
+  }
+  if (refusal) {
+    return finish({
+      mode,
+      modeReason,
+      repo: info?.repo ?? null,
+      tag: pins.tag,
+      results,
+      refusal,
+      strict,
+    });
+  }
+
+  try {
+    if (snapshot) {
+      try {
+        results.push(checkKitOwnedTrees({ runner, cwd: root, snapshot }));
+      } catch (err) {
+        results.push(
+          result("kit-owned-trees", "Kit-owned paths match the pinned tag", "fail", err.message),
+        );
+      }
+    }
+
+    if (mode === "ci") {
+      results.push(
+        ...skipAll(
+          LOCAL_ONLY_CHECKS,
+          `CI mode (${modeReason}): needs a local run with an admin gh login.`,
+        ),
+      );
+    } else {
+      results.push(...localChecks({ runner, cwd, info, files, callers, snapshot }));
+    }
+  } finally {
+    snapshot?.cleanup();
+  }
+  return finish({
+    mode,
+    modeReason,
+    repo: info?.repo ?? null,
+    tag: pins.tag,
+    results,
+    refusal: null,
+    strict,
+  });
+}
+
+function repoInfo(github, repoArg) {
+  return github.repoInfo(repoArg);
+}
+
+const TITLES = Object.fromEntries(LOCAL_ONLY_CHECKS);
+
+/** Run one check; an exception becomes a FAIL for that check, never a silent pass. */
+export function guarded(id, run) {
+  try {
+    return run();
+  } catch (err) {
+    return result(
+      id,
+      TITLES[id] ?? id,
+      "fail",
+      `Check crashed: ${firstLine(err?.message ?? err)}`,
+      {
+        details: ["This is a bug in doctor; the other checks still ran."],
+      },
+    );
+  }
+}
+
+function localChecks({ runner, cwd, info, files, callers, snapshot }) {
+  const github = createGitHub(runner, { cwd, hostname: info.host ?? null });
+  const { repo, owner, ownerType, defaultBranch } = info;
+  const raw = [];
+  const out = { push: (...items) => raw.push(...items) };
+
+  if (snapshot) {
+    let requirements = null;
+    out.push(
+      guarded("secrets", () => {
+        requirements = deriveRequirements(callers, (file) =>
+          snapshot.readFile(`.github/workflows/${file}`),
+        );
+        return checkSecrets({ github, repo, ownerType, requirements });
+      }),
+    );
+    out.push(
+      guarded("variables", () =>
+        checkVariables({
+          github,
+          repo,
+          ownerType,
+          requirements: requirements ?? { variables: deriveVariables(callers) },
+        }),
+      ),
+    );
+  } else {
+    out.push(
+      ...skipAll(
+        LOCAL_ONLY_CHECKS.slice(0, 1),
+        "Needs the pinned tag's reusable workflows; fix the pins first.",
+      ),
+    );
+    // Variables come from the Caller files alone.
+    out.push(
+      guarded("variables", () =>
+        checkVariables({
+          github,
+          repo,
+          ownerType,
+          requirements: { variables: deriveVariables(callers) },
+        }),
+      ),
+    );
+  }
+
+  const readReusable = snapshot ? (file) => snapshot.readFile(`.github/workflows/${file}`) : null;
+  if (callers.length) {
+    out.push(guarded("trigger-labels", () => checkLabels({ github, repo, callers, readReusable })));
+  } else
+    out.push(
+      result(
+        "trigger-labels",
+        "Trigger labels exist",
+        "skip",
+        "No Caller to read Trigger labels from.",
+      ),
+    );
+
+  out.push(guarded("claude-app", () => checkClaudeApp({ github, repo, owner, ownerType })));
+
+  let rulesets = null;
+  let rulesetError = null;
+  try {
+    rulesets = loadRulesets(github, repo);
+  } catch (err) {
+    rulesetError = `Could not read rulesets: ${err.message}`;
+  }
+  if (rulesets) {
+    out.push(guarded("ruleset-update", () => checkUpdateRule(rulesets, { defaultBranch })));
+    out.push(guarded("ruleset-creation", () => checkCreationRule(rulesets)));
+    out.push(guarded("ruleset-tags", () => checkTagRuleset(rulesets)));
+  } else {
+    out.push(...skipAll(LOCAL_ONLY_CHECKS.slice(4, 7), rulesetError));
+  }
+  out.push(guarded("release-tag-push", () => checkPersonalTagPush({ ownerType, files })));
+  return raw;
+}
+
+function finish({ mode, modeReason, repo, tag, results, refusal, strict }) {
+  const final = strict
+    ? results.map((r) => (r.status === "warn" ? { ...r, status: "fail", strict: true } : r))
+    : results;
+  const failed = refusal !== null || final.some((r) => r.status === "fail");
+  return { mode, modeReason, repo, tag, results: final, refusal, exitCode: failed ? 1 : 0 };
+}
+
+const LABEL = { pass: "PASS", warn: "WARN", fail: "FAIL", skip: "SKIP" };
+
+/** Plain-text report. Every line is sanitized for terminals and CI logs. */
+export function formatReport(report, opts = {}) {
+  return formatLines(report, opts).map(sanitizeLine).join("\n");
+}
+
+function formatLines(report, { version } = {}) {
+  const lines = [];
+  lines.push(`agent-kit doctor${version ? ` ${version}` : ""}`);
+  lines.push(`  repository: ${report.repo ?? "(unknown)"}`);
+  lines.push(`  pinned tag: ${report.tag ?? "(none)"}`);
+  lines.push(`  mode:       ${report.mode}${report.modeReason ? ` (${report.modeReason})` : ""}`);
+  lines.push("");
+  if (report.refusal) {
+    for (const r of report.results) lines.push(...formatResult(r));
+    lines.push(`REFUSED  ${report.refusal}`);
+    lines.push("");
+    lines.push("Result: refused (exit 1).");
+    return lines;
+  }
+  for (const r of report.results) lines.push(...formatResult(r));
+  const count = (s) => report.results.filter((r) => r.status === s).length;
+  const skipped = report.results.filter((r) => r.status === "skip");
+  lines.push("");
+  lines.push(
+    `Result: ${count("fail")} failed, ${count("warn")} warning(s), ${skipped.length} skipped, ${count("pass")} passed (exit ${report.exitCode}).`,
+  );
+  if (skipped.length) {
+    lines.push(
+      `Skipped checks did not run and are not passes: ${skipped.map((r) => r.id).join(", ")}.`,
+    );
+  }
+  if (report.results.some((r) => r.fix.length)) {
+    lines.push(
+      "Lines starting with $ are POSIX shell (bash, zsh) commands for you to run; doctor ran none of them.",
+    );
+  }
+  return lines;
+}
+
+export function formatResult(r) {
+  const out = [
+    `${LABEL[r.status]}  ${r.title}: ${r.summary}${r.strict ? " (warning; failed by --strict)" : ""}`,
+  ];
+  for (const d of r.details) out.push(`      ${d}`);
+  for (const f of r.fix) out.push(`      $ ${f}`);
+  return out;
+}
+
+/** doctor --ci's pin and Kit-owned path checks, against an already-fetched tag. */
+export function fileAndPinChecks({ runner, root, snap }) {
+  let pins;
+  try {
+    pins = checkPins(readWorkflows(root).files);
+  } catch (err) {
+    return [result("pins", "uses: pins agree", "fail", firstLine(err?.message ?? err))];
+  }
+  const results = [pins.result];
+  if (pins.tag !== snap.tag) {
+    results.push(
+      result(
+        "kit-owned-trees",
+        "Kit-owned paths match the pinned tag",
+        "fail",
+        `The pins do not all name ${snap.tag}.`,
+      ),
+    );
+    return results;
+  }
+  try {
+    results.push(checkKitOwnedTrees({ runner, cwd: root, snapshot: snap }));
+  } catch (err) {
+    results.push(
+      result("kit-owned-trees", "Kit-owned paths match the pinned tag", "fail", err.message),
+    );
+  }
+  return results;
+}
+
+/**
+ * Print fileAndPinChecks results under a heading, for init and upgrade.
+ * Returns true when one failed.
+ */
+export function printFileAndPinChecks(out, results) {
+  out("Checks (as doctor --ci):");
+  for (const r of results) for (const line of formatResult(r)) out(line);
+  return results.some((r) => r.status === "fail");
+}

package/src/exec.mjs

@@ -0,0 +1,64 @@
+// Runs `git` and `gh` as argument arrays, never through a shell, so no string
+// from a Consumer file or a GitHub response is ever parsed as shell syntax.
+// Every module takes a runner as a parameter; tests inject a fake one.
+
+import { spawnSync } from "node:child_process";
+
+const ALLOWED = new Set(["git", "gh"]);
+
+/**
+ * @typedef {{ status: number | null, stdout: string, stderr: string }} RunResult
+ * @typedef {{ status: number | null, stdout: Buffer, stderr: string }} BufferResult
+ * @typedef {(cmd: string, args: string[], opts?: { cwd?: string, env?: NodeJS.ProcessEnv, encoding?: "utf8" | "buffer" }) => RunResult} Runner
+ *   With `encoding: "buffer"`, stdout is the raw bytes (a Buffer): use it for
+ *   file contents, which need not be UTF-8. stderr is always text.
+ */
+
+/** @type {Runner} */
+export function systemRunner(cmd, args, opts = {}) {
+  if (!ALLOWED.has(cmd)) throw new Error(`refusing to run ${cmd}: only git and gh are allowed`);
+  if (!Array.isArray(args) || args.some((a) => typeof a !== "string")) {
+    throw new TypeError("runner arguments must be an array of strings");
+  }
+  const result = spawnSync(cmd, args, {
+    cwd: opts.cwd,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1", ...opts.env },
+    encoding: "buffer",
+    shell: false,
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const raw = opts.encoding === "buffer";
+  if (result.error) {
+    return {
+      status: null,
+      stdout: raw ? Buffer.alloc(0) : "",
+      stderr: `${cmd}: ${result.error.message}`,
+    };
+  }
+  const stdout = result.stdout ?? Buffer.alloc(0);
+  return {
+    status: result.status,
+    stdout: raw ? stdout : stdout.toString("utf8"),
+    stderr: (result.stderr ?? Buffer.alloc(0)).toString("utf8"),
+  };
+}
+
+/**
+ * The line of a command's stderr that says what went wrong, for short
+ * messages: the first `fatal:` or `error:` line, else the first line that is
+ * not a `warning:` or `hint:` (git prints those before the real error, for
+ * example about line endings), else the first non-empty line.
+ */
+export function firstLine(text) {
+  const lines = String(text ?? "")
+    .split(/\r\n|\r|\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  return (
+    lines.find((l) => /^(fatal|error):/i.test(l)) ??
+    lines.find((l) => !/^(warning|hint):/i.test(l)) ??
+    lines[0] ??
+    ""
+  );
+}