Merge remote-tracking branch 'origin/main' into feat/pipeline-driven-ship-commands

# Conflicts:
#	server/__tests__/lanes-cli.test.js

server/lib/ci-status.js

@@ -0,0 +1,61 @@
+/**
+ * @file Turns a GitHub Actions run for one ref into a single derived fact —
+ * {state, checks} — for ship-feature-lane's Stage 13 CI-wait. Deliberately a
+ * snapshot, not a poll loop: the driving skill owns the wait/retry decision
+ * (docs/LANES.md "Orchestration: what CCAM does NOT do"), this module only
+ * reports what gh already knows.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { gh } = require("./gh");
+
+/** A 7-40 char hex string reads as a commit sha; anything else is a branch name. */
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+
+/**
+ * @param {string} cwd - The lane's repo directory (gh resolves the GitHub
+ *   repo from this directory's git remote).
+ * @param {string} ref - A branch name or commit sha.
+ * @returns {Promise<{state: "success"|"failure"|"pending", ref: string, checks: Array}>}
+ */
+async function ciStatus(cwd, ref) {
+  const refFlag = SHA_RE.test(ref) ? "--commit" : "--branch";
+  const { stdout: listOut } = await gh(cwd, [
+    "run",
+    "list",
+    refFlag,
+    ref,
+    "--json",
+    "databaseId,status,conclusion",
+    "--limit",
+    "1",
+  ]);
+  const runs = JSON.parse(listOut);
+  if (runs.length === 0) {
+    return { state: "pending", ref, checks: [] };
+  }
+  const run = runs[0];
+  if (run.status !== "completed") {
+    return { state: "pending", ref, checks: [] };
+  }
+
+  const { stdout: viewOut } = await gh(cwd, [
+    "run",
+    "view",
+    String(run.databaseId),
+    "--json",
+    "jobs",
+  ]);
+  const { jobs } = JSON.parse(viewOut);
+  const checks = jobs.map((job) => ({
+    name: job.name,
+    conclusion: job.conclusion || job.status,
+    url: job.url || null,
+  }));
+
+  const FAILING = new Set(["failure", "cancelled", "timed_out", "action_required"]);
+  const state = checks.some((c) => FAILING.has(c.conclusion)) ? "failure" : "success";
+  return { state, ref, checks };
+}
+
+module.exports = { ciStatus };

server/lib/gh.js

@@ -0,0 +1,36 @@
+/**
+ * @file Thin execFile wrapper around the GitHub CLI (`gh`), used by
+ * server/lib/ci-status.js to read Actions run state. Mirrors worktree.js's
+ * git() helper's shape (cwd-scoped, throws with structured .gh details on
+ * failure) but has no env-scrubbing to do — gh doesn't read GIT_* variables.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { execFile } = require("node:child_process");
+const { promisify } = require("node:util");
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Run `gh <args>` in `cwd`. Resolves `{ stdout, stderr }` on a zero exit.
+ * On failure, throws an Error with `.gh = { args, code, stderr }` — `.code`
+ * is `"ENOGH"` when the binary itself is missing, otherwise the process's
+ * exit code.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+async function gh(cwd, args) {
+  try {
+    const result = await execFileAsync("gh", args, { cwd, maxBuffer: 8 * 1024 * 1024 });
+    return { stdout: result.stdout, stderr: result.stderr };
+  } catch (err) {
+    const error = new Error(`gh ${args[0]} failed`);
+    error.code = err.code === "ENOENT" ? "ENOGH" : err.code;
+    error.gh = { args, code: err.code, stderr: err.stderr || "" };
+    throw error;
+  }
+}
+
+module.exports = { gh };