Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
#!/usr/bin/env node
/**
* The CI gate's verdict, with CANCELLED told apart from FAILED.
*
* The gate used to collapse every non-`success`/`skipped` needs-result into
* one "did not pass" line, so a job that GitHub cancelled out from under us
* read exactly like a red test suite (issue 7437). That sends the next reader
* hunting for a failing assertion that does not exist, and it hides the one
* fact that decides what to do next: whether anything actually failed.
*
* Three verdicts, not two:
* - pass — every selected job was `success` or `skipped`.
* - cancelled — at least one job was `cancelled` and NOTHING failed. There
* is no test failure to chase. Still non-zero: a cancelled
* run proves nothing and must not be merged.
* - failure — at least one job genuinely failed. Any cancelled jobs are
* listed beside it.
*
* The catch, and why this talks to the API at all: `needs.<job>.result` is the
* job's CONCLUSION, and a job that is cancelled mid-step (a run-wide cancel, or
* its own `timeout-minutes`) reads `cancelled` even when a step had already
* failed (issue 7574). A cancelled job keeps its STEPS'
* conclusions, so when — and only when — the cancelled verdict is about to be
* printed, the run's jobs are queried for a failed step. Best-effort by design:
* an API failure falls back to today's wording rather than turning a cancelled
* run red or green on a network blip.
*
* Scope, so the next reader is not misled: this runs only when the GATE job
* itself runs. A job timeout leaves the gate running (`if: always()`), so the
* culprit lookup above explains it here. An EXTERNAL run-wide cancellation
* takes the gate with it, and then the explanation comes from the recovery
* workflow instead — see
* "External cancellation and one automatic retry" in docs/GITHUB_ACTIONS.md.
*
* Reads `CI_GATE_RESULT_<JOB>` out of the environment rather than taking
* arguments, so adding a job to the gate is one workflow line and no code
* change.
*/
import { isDirectlyInvoked } from './lib/directInvocation.js';
import {
currentRunTargetFromEnv, fetchJobsWithFailedSteps, formatFailedJob,
} from './lib/githubActionsApi.js';
import { writeStepSummary } from './lib/githubOutput.js';
const RESULT_ENV_PREFIX = 'CI_GATE_RESULT_';
/** GitHub's `needs.<job>.result` values that do not block the gate. */
const PASSING_RESULTS = new Set(['success', 'skipped']);
/**
* `Full CI Gate` sets `CI_GATE_REQUIRE_SUCCESS`, because a `skipped` input
* must NOT satisfy it. `scripts/verify-ci-status.js` lets a release skip the
* complete suite on the strength of that check, so accepting anything short of
* `success` there would ship an untested tree.
*/
const STRICT_PASSING_RESULTS = new Set(['success']);
const DEFAULT_LABEL = 'CI Gate';
/**
* The gate jobs' own display names, excluded from the culprit lookup. Both fail
* downstream of any red run — by design, that is their job — so naming one as
* the culprit would point every reader back at the gate they are already
* looking at. Asserted against ci.yml's `name:` lines in the wiring test.
*/
const GATE_JOB_NAMES = new Set(['CI Gate', 'Full CI Gate']);
const CULPRIT_TIMEOUT_MS = 10_000;
const TROUBLESHOOTING_ANCHOR = '"CI red with every job \'cancelled\'" in docs/TROUBLESHOOTING.md';
const pair = ({ job, result }) => `${job}=${result}`;
/**
* Read the `CI_GATE_RESULT_<JOB>` variables into `[{ job, result }]`.
*
* `CI_GATE_RESULT_WINDOWS_SERVER` names the `windows-server` job: GitHub
* expression syntax cannot produce a hyphen in an env key, so the workflow
* spells it with an underscore and the job id is restored here.
*
* @param {NodeJS.ProcessEnv} [env]
* @returns {Array<{job: string, result: string}>} declaration order preserved
*/
export function collectGateResults(env = process.env) {
return Object.entries(env)
.filter(([key]) => key.startsWith(RESULT_ENV_PREFIX) && key.length > RESULT_ENV_PREFIX.length)
.map(([key, value]) => ({
job: key.slice(RESULT_ENV_PREFIX.length).toLowerCase().replace(/_/g, '-'),
// An unset `needs.<job>.result` arrives as the empty string. Naming it
// keeps it out of the "passed" bucket instead of silently vanishing.
result: (typeof value === 'string' && value.trim()) || 'unknown',
}));
}
/**
* Classify gate results into a verdict plus the lines to print.
*
* @param {Array<{job: string, result: string}>} results
* @param {string} [label] - The gate's display name, for the message.
* @param {object} [options]
* @param {boolean} [options.requireSuccess] - when true, `skipped` does not pass
* @param {Array<{name: string, steps: string[]}>|null} [options.culprits] - jobs
* the Actions API reports with a FAILED STEP, consulted only for a run that
* would otherwise read as cancelled. THREE states, not two: a non-empty list
* is a red run; `[]` is "looked, nothing failed"; `null` is "could not look".
* The last two both stay cancelled, but they warrant different advice — see
* the cancelled branch.
* @returns {{verdict: 'pass'|'cancelled'|'failure', lines: string[]}}
*/
export function summarizeGateResults(
results,
label = DEFAULT_LABEL,
{ requireSuccess = false, culprits = null } = {},
) {
const passing = requireSuccess ? STRICT_PASSING_RESULTS : PASSING_RESULTS;
const passed = results.filter(({ result }) => passing.has(result));
const cancelled = results.filter(({ result }) => result === 'cancelled').map(({ job }) => job);
// Anything neither passing nor cancelled is a failure — `failure`, and also
// the `unknown` above. Defaulting an unrecognised result to "failed" is the
// safe direction: it blocks with a loud message instead of being waved
// through as collateral of a cancel.
const failed = results
.filter(({ result }) => !passing.has(result) && result !== 'cancelled')
.map(pair);
const finished = () => (passed.length
? `Jobs that finished: ${passed.map(pair).join(', ')}`
: 'No job reached a conclusion.');
if (failed.length) {
return {
verdict: 'failure',
lines: [
`❌ ${label}: selected CI jobs did not pass.`,
`Failed jobs: ${failed.join(', ')}`,
...(cancelled.length
? [`Also cancelled: ${cancelled.join(', ')}`]
: []),
finished(),
],
};
}
if (cancelled.length) {
if (culprits?.length) {
return {
verdict: 'failure',
lines: [
`❌ ${label}: a job FAILED. Its conclusion reads cancelled because the run`
+ ' was stopped before GitHub recorded the failure.',
...culprits.map((job) => `Failing job: ${formatFailedJob(job)}`),
`Cancelled jobs: ${cancelled.join(', ')}`,
finished(),
'Open that job and read its log. `gh run view --log-failed` returns nothing'
+ ' for this shape of run, because no job concluded `failure`.',
],
};
}
return {
verdict: 'cancelled',
lines: [
`🚫 ${label}: this run was CANCELLED, not failed — no job REPORTED a failure.`,
`Cancelled jobs: ${cancelled.join(', ')}`,
finished(),
// This distinction is load-bearing. The old line said "No test failed",
// and twice (#7482, #7571) that sent a reader straight to the billing
// dashboard while a real assertion sat unread in a job log: a job
// cancelled mid-step concludes `cancelled` even when a step failed, so
// NOTHING in the run metadata reads `failure`. That is now CHECKED rather than
// guessed — but only when the lookup ran, so the two states say
// different things instead of sharing the more alarming wording.
...(culprits
? ["Checked every job's STEP conclusions too, and none failed — so this"
+ ' is not a failed step hidden behind a cancelled conclusion.']
: ["This run's step conclusions could NOT be read, so a cancelled"
+ ' conclusion here does NOT mean no test failed: a job cancelled'
+ ' mid-step hides a failed step behind a cancelled conclusion.'
+ ' READ THE JOB LOGS FIRST — use the full `--log` and grep for'
+ ' `FAIL ` or `AssertionError`.']),
// Every ci.yml job sets its own `timeout-minutes`, so the limit that
// usually bites is the job's (20 minutes for DB tests), not GitHub's
// 6-hour default. GitHub records either as `cancelled`, so a slow apt
// mirror or a hung test reads like a superseded push (#10369).
'Otherwise: a job that ran past its `timeout-minutes` (or the 6-hour'
+ ' default) is recorded as `cancelled` rather than `timed_out` — open'
+ ' the cancelled job and look for an annotation reading "exceeded the'
+ ' maximum execution time"; the step that was running when it hit the'
+ ' limit is the slow one (a stalled package download, a hang),'
+ ' a newer push superseded this run (cancel-in-progress leaves a NEWER'
+ ' run for the branch), or GitHub cancelled it externally — the Actions'
+ ' spending limit, which is the LAST hypothesis, not the first.',
`Working through those in order: ${TROUBLESHOOTING_ANCHOR}`,
],
};
}
if (!results.length) {
// Fail closed. A green required check that examined nothing is worse
// than a red one: it is indistinguishable from a real pass.
return {
verdict: 'failure',
lines: [
`❌ ${label}: no job results were supplied, so nothing was checked.`,
"Every job in the gate's `needs:` list needs a CI_GATE_RESULT_<JOB>"
+ " environment entry in .github/workflows/ci.yml.",
],
};
}
return {
verdict: 'pass',
lines: [`✅ ${label} passed: ${results.map(pair).join(', ')}`],
};
}
/**
* Jobs in THIS run that carry a failed step, the gate jobs excluded.
*
* `null` on an unusable environment or a failed lookup, kept distinct from the
* empty array: both keep the cancelled verdict, but only "looked and found
* none" earns the wording that rules a hidden failed step out. A failed lookup
* must never invent a failure the run may not have, nor vouch for its absence.
*
* @param {NodeJS.ProcessEnv} env
* @param {typeof fetch} fetchImpl
* @returns {Promise<Array<{name: string, steps: string[]}>|null>}
*/
async function findCulprits(env, fetchImpl) {
const target = currentRunTargetFromEnv(env);
const jobs = await fetchJobsWithFailedSteps(fetchImpl, target && {
...target,
timeoutMs: CULPRIT_TIMEOUT_MS,
});
return jobs && jobs.filter(({ name }) => !GATE_JOB_NAMES.has(name));
}
/**
* Print the verdict — to the step log and to the run summary — and report
* whether the gate passed.
*
* @param {object} [options]
* @param {NodeJS.ProcessEnv} [options.env]
* @param {{log?: Function, error?: Function}} [options.logger]
* @param {Function} [options.writeSummary] - injectable step-summary writer
* @param {typeof fetch} [options.fetchImpl] - injectable fetch for tests
* @returns {Promise<{verdict: string, ok: boolean, lines: string[]}>}
*/
export async function reportGate({
env = process.env,
logger = console,
writeSummary = writeStepSummary,
fetchImpl = globalThis.fetch,
} = {}) {
const label = env.CI_GATE_LABEL?.trim() || DEFAULT_LABEL;
const results = collectGateResults(env);
const requireSuccess = env.CI_GATE_REQUIRE_SUCCESS === 'true';
const provisional = summarizeGateResults(results, label, { requireSuccess });
// The lookup runs ONLY for the cancelled verdict. Every other one already
// names its cause, and a gate that queried the API on every green run would
// spend a request per build to learn nothing. Re-summarizing is a second pass
// over a handful of strings — cheaper than threading a lazy resolver through
// a pure function for the sake of one rare branch.
const { verdict, lines } = provisional.verdict === 'cancelled'
? summarizeGateResults(results, label, {
requireSuccess,
culprits: await findCulprits(env, fetchImpl),
})
: provisional;
const ok = verdict === 'pass';
for (const line of lines) (ok ? logger.log : logger.error)?.call(logger, line);
// The summary page too: nobody expands a step log before concluding "CI is
// red". Every value here is a job id or a GitHub result string, never event
// payload text.
writeSummary(`### ${ok ? '✅' : '🚫'} ${label}\n\n${lines.map((line) => `- ${line}`).join('\n')}`, env);
return { verdict, ok, lines };
}
if (isDirectlyInvoked(import.meta.url)) {
if (!(await reportGate()).ok) process.exitCode = 1;
}