feat(cicd): add branch follower taskrun drilldown

This commit is contained in:
Codex
2026-07-03 23:32:39 +00:00
parent 2a5c8644dd
commit 7004f8f7ab
7 changed files with 574 additions and 5 deletions
+53 -3
View File
@@ -29,6 +29,7 @@ import { runNativeK8sJob, runNativeTektonPipelineRun } from "./cicd-native";
import { argoApplicationReady, nativeArgoSummary, nativeGitMirrorReady, nativeGitMirrorRequired, nativeGitMirrorSummary, nativePipelineRunSummary, nativeRuntimeSummary, pipelineRunSucceeded, runtimeTargetShaFromWorkloads, runtimeWorkloadsReady } from "./cicd-native-summary";
import { invalidRuntimeReuseConfig, missingRuntimeReuseConfig, parseRuntimeReuseConfig, RUNTIME_REUSE_CONFIG_PATH, runtimeReuseService, summarizeRuntimeReuseConfig, type RuntimeReuseConfig } from "./cicd-reuse-config";
import { prioritizedTaskRunItems } from "./cicd-taskruns";
import { runBranchFollowerTaskRunDrillDown } from "./cicd-taskrun-drilldown";
import type { AdapterSummary, BranchFollowerAction, BranchFollowerDebugStep, BranchFollowerPhase, BranchFollowerRegistry, ControllerSpec, FollowerSpec, FollowerState, K8sFollowerStateRead, K8sStateRead, NativeCloseoutWaitResult, NativeK8sJobResult, NativeStatusSpec, NativeWorkloadSpec, OutputMode, ParsedOptions, StageTiming, TriggerResult } from "./cicd-types";
import {
arrayField,
@@ -49,7 +50,7 @@ const SPEC_VERSION = "draft-2026-07-03-p0-branch-follower";
export function cicdHelp(): unknown {
return {
command: "cicd branch-follower plan|apply|status|run-once|debug-step|cleanup-state|events|logs",
command: "cicd branch-follower plan|apply|status|run-once|debug-step|cleanup-state|events|logs|taskrun",
output: "text by default; use --json, --raw, or -o json|yaml for machine output",
usage: [
"bun scripts/cli.ts cicd branch-follower plan",
@@ -64,6 +65,8 @@ export function cicdHelp(): unknown {
"bun scripts/cli.ts cicd branch-follower cleanup-state --follower web-probe-sentinel-master --confirm",
"bun scripts/cli.ts cicd branch-follower events --follower agentrun-jd01-v02",
"bun scripts/cli.ts cicd branch-follower logs --follower web-probe-sentinel-master",
"bun scripts/cli.ts cicd branch-follower status --follower hwlab-jd01-v03 --taskrun runtime-ready --logs-tail 120 --json",
"bun scripts/cli.ts cicd branch-follower taskrun --follower hwlab-jd01-v03 --taskrun runtime-ready --logs-tail 120 --json",
],
config: DEFAULT_CONFIG_PATH,
spec: `${SPEC_REF} ${SPEC_VERSION}`,
@@ -75,7 +78,7 @@ export async function runCicdCommand(_config: UniDeskConfig | null, args: string
const top = args[0];
if (top === undefined || isHelpToken(top)) return renderMachine("cicd", cicdHelp(), "json");
if (top !== "branch-follower") {
throw new Error("cicd usage: cicd branch-follower plan|apply|status|run-once|debug-step|cleanup-state|events|logs");
throw new Error("cicd usage: cicd branch-follower plan|apply|status|run-once|debug-step|cleanup-state|events|logs|taskrun");
}
const options = parseOptions(args.slice(1));
const command = commandLabel(options);
@@ -87,6 +90,7 @@ export async function runCicdCommand(_config: UniDeskConfig | null, args: string
case "apply":
return renderResult(command, await applyController(registry, options), options);
case "status":
if (options.taskRunName !== null) return renderResult(command, await runTaskRunDrillDown(registry, options), options);
return renderResult(command, await buildStatus(registry, options), options);
case "run-once":
return renderResult(command, await runOnce(registry, options), options);
@@ -97,6 +101,8 @@ export async function runCicdCommand(_config: UniDeskConfig | null, args: string
case "events":
case "logs":
return renderResult(command, await runFollowerDrillDown(registry, options), options);
case "taskrun":
return renderResult(command, await runTaskRunDrillDown(registry, options), options);
case "help":
return renderMachine(command, cicdHelp(), "json");
}
@@ -107,7 +113,7 @@ function parseOptions(args: string[]): ParsedOptions {
if (actionToken === undefined || isHelpToken(actionToken)) {
return defaultOptions("help", args.slice(actionToken === undefined ? 0 : 1));
}
if (!["plan", "apply", "status", "run-once", "debug-step", "cleanup-state", "events", "logs"].includes(actionToken)) {
if (!["plan", "apply", "status", "run-once", "debug-step", "cleanup-state", "events", "logs", "taskrun"].includes(actionToken)) {
throw new Error(`cicd branch-follower unknown action: ${actionToken}`);
}
const action = actionToken as BranchFollowerAction;
@@ -147,6 +153,14 @@ function parseOptions(args: string[]): ParsedOptions {
options.recordState = true;
} else if (arg === "--step") {
options.debugStep = debugStepOption(valueOption(rest, ++index, arg));
} else if (arg === "--taskrun" || arg === "--task-run") {
options.taskRunName = simpleK8sObjectName(valueOption(rest, ++index, arg), arg);
} else if (arg === "--pipelinerun" || arg === "--pipeline-run") {
options.pipelineRunName = simpleK8sObjectName(valueOption(rest, ++index, arg), arg);
} else if (arg === "--logs-tail") {
options.logsTailLines = positiveInt(valueOption(rest, ++index, arg), arg);
} else if (arg === "--max-log-bytes") {
options.maxLogBytes = positiveInt(valueOption(rest, ++index, arg), arg);
} else if (arg === "-o" || arg === "--output") {
const value = valueOption(rest, ++index, arg);
if (value !== "json" && value !== "yaml" && value !== "wide" && value !== "text") throw new Error(`${arg} must be json, yaml, wide, or text`);
@@ -178,6 +192,12 @@ function parseOptions(args: string[]): ParsedOptions {
if (options.action === "debug-step" && options.followerId === null) {
throw new Error("debug-step requires --follower <id>");
}
if (options.action === "taskrun" && options.taskRunName === null) {
throw new Error("taskrun requires --taskrun <taskrun-name|pipeline-task>");
}
if (options.taskRunName !== null && options.followerId === null) {
throw new Error("--taskrun requires --follower <id>");
}
return options;
}
@@ -206,6 +226,10 @@ function defaultOptions(action: BranchFollowerAction, _args: string[]): ParsedOp
raw: false,
recordState: false,
debugStep: null,
taskRunName: null,
pipelineRunName: null,
logsTailLines: null,
maxLogBytes: null,
output: "human",
limit: 20,
tailBytes: 12000,
@@ -224,6 +248,11 @@ function simpleId(value: string, option: string): string {
return value;
}
function simpleK8sObjectName(value: string, option: string): string {
if (!/^[A-Za-z0-9._-]+$/u.test(value)) throw new Error(`${option} must be a Kubernetes object or task id`);
return value;
}
function positiveInt(value: string, option: string): number {
const parsed = Number(value);
if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${option} must be a positive integer`);
@@ -337,6 +366,7 @@ function parseFollower(root: Record<string, unknown>, index: number): FollowerSp
const budgets = recordField(root, "budgets", label);
const commands = recordField(root, "commands", label);
const nativeStatus = recordField(root, "nativeStatus", label);
const drillDown = recordField(root, "drillDown", label);
const closeout = recordField(root, "closeout", label);
const configRefs = stringMap(recordField(target, "configRefs", `${label}.target`), `${label}.target.configRefs`);
return {
@@ -376,6 +406,7 @@ function parseFollower(root: Record<string, unknown>, index: number): FollowerSp
logs: parseCommand(recordField(commands, "logs", `${label}.commands`), `${label}.commands.logs`),
},
nativeStatus: parseNativeStatus(nativeStatus, `${label}.nativeStatus`),
drillDown: parseDrillDown(drillDown, `${label}.drillDown`),
closeoutChecks: stringArrayField(closeout, "checks", `${label}.closeout`),
};
}
@@ -438,6 +469,16 @@ function parseCommand(root: Record<string, unknown>, label: string): CommandSpec
};
}
function parseDrillDown(root: Record<string, unknown>, label: string): FollowerSpec["drillDown"] {
return {
taskRunTimeoutSeconds: integerField(root, "taskRunTimeoutSeconds", label),
logsTailLines: integerField(root, "logsTailLines", label),
maxLogBytes: integerField(root, "maxLogBytes", label),
maxMessageBytes: integerField(root, "maxMessageBytes", label),
maxContainers: integerField(root, "maxContainers", label),
};
}
function optionalStringArrayField(root: Record<string, unknown>, key: string, label: string): string[] {
return root[key] === undefined ? [] : stringArrayField(root, key, label);
}
@@ -477,6 +518,7 @@ function buildPlan(registry: BranchFollowerRegistry, options: ParsedOptions): Re
},
target: follower.target,
budgets: follower.budgets,
drillDown: follower.drillDown,
commands: redactCommands(follower),
nativeStatus: nativeStatusPlan(follower.nativeStatus),
closeoutChecks: follower.closeoutChecks,
@@ -765,6 +807,13 @@ async function runFollowerDrillDown(registry: BranchFollowerRegistry, options: P
};
}
async function runTaskRunDrillDown(registry: BranchFollowerRegistry, options: ParsedOptions): Promise<Record<string, unknown>> {
if (options.followerId === null) throw new Error("--taskrun requires --follower <id>");
const follower = registry.followers.find((item) => item.id === options.followerId);
if (follower === undefined) throw new Error(`unknown follower ${options.followerId}`);
return runBranchFollowerTaskRunDrillDown(registry, follower, options, runKubeScript);
}
async function decideAndMaybeTrigger(
registry: BranchFollowerRegistry,
follower: FollowerSpec,
@@ -2776,6 +2825,7 @@ function tailText(text: string, maxChars: number): string {
}
function commandLabel(options: ParsedOptions): string {
if (options.taskRunName !== null) return "cicd branch-follower taskrun";
return `cicd branch-follower ${options.action}`;
}
+55
View File
@@ -2,6 +2,7 @@
// Responsibility: bounded human summaries for branch-follower events/logs gates.
export function renderDrillDownHuman(payload: Record<string, unknown>): string {
if (payload.action === "taskrun") return renderTaskRunHuman(payload);
if (payload.follower === undefined) {
const followers = arrayRecords(payload.followers);
return [
@@ -26,6 +27,60 @@ export function renderDrillDownHuman(payload: Record<string, unknown>): string {
].filter((line) => line !== "").join("\n");
}
function renderTaskRunHuman(payload: Record<string, unknown>): string {
const result = asOptionalRecord(payload.result);
const taskRun = asOptionalRecord(result?.taskRun);
const pod = asOptionalRecord(result?.pod);
const policy = asOptionalRecord(payload.policy);
const containers = arrayRecords(result?.containers);
const logs = arrayRecords(result?.logs);
const timing = asOptionalRecord(result?.nodeCicdTiming);
const query = asOptionalRecord(payload.query);
const command = asOptionalRecord(payload.command);
return [
`CI/CD BRANCH-FOLLOWER TASKRUN (${payload.ok === false ? "failed" : "ok"})`,
"",
table(
["FOLLOWER", "ADAPTER", "TASKRUN", "PIPELINERUN", "POD", "STATUS", "REASON", "DURATION", "CONTAINERS"],
[[
payload.follower,
payload.adapter ?? "-",
taskRun?.name ?? query?.taskRun ?? "-",
taskRun?.pipelineRun ?? query?.pipelineRun ?? "-",
taskRun?.podName ?? "-",
asOptionalRecord(taskRun?.condition)?.status ?? "-",
asOptionalRecord(taskRun?.condition)?.reason ?? "-",
taskRun?.durationSeconds ?? "-",
pod?.containerCount ?? "-",
]],
),
containers.length === 0 ? "" : `\nCONTAINERS\n${table(["NAME", "CONTAINER", "STATE", "REASON", "EXIT", "STARTED", "FINISHED", "MESSAGE"], containers.map(containerRow))}`,
logs.length === 0 ? "" : `\nLOG TAILS\n${table(["POD", "CONTAINER", "LINES", "BYTES", "TIMING"], logs.map((item) => [item.pod, item.container, item.lineCount, item.bytes, asOptionalRecord(item.nodeCicdTiming) === null ? "-" : "node-cicd-timing"]))}`,
timing === null ? "" : `\nNODE_CICD_TIMING\n${JSON.stringify(timing, null, 2)}`,
"",
`policy: tailLines=${policy?.logsTailLines ?? "-"} maxLogBytes=${policy?.maxLogBytes ?? "-"} timeoutSeconds=${policy?.taskRunTimeoutSeconds ?? "-"} maxContainers=${policy?.maxContainers ?? "-"}`,
command?.stderrTail ? `stderr: ${command.stderrTail}` : "",
"",
].filter((line) => line !== "").join("\n");
}
function containerRow(item: Record<string, unknown>): unknown[] {
const terminated = asOptionalRecord(item.terminated);
const waiting = asOptionalRecord(item.waiting);
const running = asOptionalRecord(item.running);
const state = terminated !== null ? "terminated" : waiting !== null ? "waiting" : running !== null ? "running" : "-";
return [
item.name,
item.containerName,
state,
terminated?.reason ?? waiting?.reason ?? "-",
terminated?.exitCode ?? "-",
terminated?.startedAt ?? running?.startedAt ?? "-",
terminated?.finishedAt ?? "-",
terminated?.message ?? waiting?.message ?? "-",
];
}
function nativeGateRows(native: Record<string, unknown> | null): unknown[][] {
if (native === null) return [];
const rows: unknown[][] = [];
+1 -1
View File
@@ -27,7 +27,7 @@ function renderHuman(command: string, payload: Record<string, unknown>, options:
if (command.endsWith(" run-once")) return renderRunOnceHuman(payload);
if (command.endsWith(" debug-step")) return renderDebugStepHuman(payload);
if (command.endsWith(" cleanup-state")) return renderCleanupStateHuman(payload);
if (command.endsWith(" events") || command.endsWith(" logs")) return renderDrillDownHuman(payload);
if (command.endsWith(" events") || command.endsWith(" logs") || command.endsWith(" taskrun")) return renderDrillDownHuman(payload);
return `${JSON.stringify(payload, null, 2)}\n`;
}
+87
View File
@@ -0,0 +1,87 @@
// SPEC: PJ2026-01060703 CI/CD branch follower TaskRun drill-down.
// Responsibility: follower-scoped read-only TaskRun/Pod/container/log-tail visibility.
import type { CommandResult } from "./command";
import type { BranchFollowerRegistry, FollowerSpec, ParsedOptions } from "./cicd-types";
import { nativeCicdScriptLoadShell } from "./cicd-native-bundle";
import { redactText, shQuote } from "./platform-infra-ops-library";
type KubeScriptRunner = (registry: BranchFollowerRegistry, options: ParsedOptions, script: string, input: string, timeoutMs: number) => CommandResult;
export async function runBranchFollowerTaskRunDrillDown(
registry: BranchFollowerRegistry,
follower: FollowerSpec,
options: ParsedOptions,
runKubeScript: KubeScriptRunner,
): Promise<Record<string, unknown>> {
if (follower.nativeStatus.tekton === null) throw new Error(`follower ${follower.id} has no Tekton native status config`);
const taskRun = options.taskRunName;
if (taskRun === null) throw new Error("taskrun drill-down requires --taskrun <taskrun-name|pipeline-task>");
const policy = {
taskRunTimeoutSeconds: options.timeoutSeconds ?? follower.drillDown.taskRunTimeoutSeconds,
logsTailLines: options.logsTailLines ?? follower.drillDown.logsTailLines,
maxLogBytes: options.maxLogBytes ?? follower.drillDown.maxLogBytes,
maxMessageBytes: follower.drillDown.maxMessageBytes,
maxContainers: follower.drillDown.maxContainers,
};
const script = [
"set -eu",
"tmpdir=$(mktemp -d)",
"cleanup() { rm -rf \"$tmpdir\"; }",
"trap cleanup EXIT INT TERM",
nativeCicdScriptLoadShell(["taskrun-drilldown.mjs"]),
`TEKTON_NAMESPACE=${shQuote(follower.nativeStatus.tekton.namespace)}`,
`TASKRUN_QUERY=${shQuote(taskRun)}`,
`PIPELINE_RUN_NAME=${shQuote(options.pipelineRunName ?? "")}`,
`PIPELINE_RUN_PREFIX=${shQuote(follower.nativeStatus.tekton.pipelineRunPrefix)}`,
`LOGS_TAIL_LINES=${policy.logsTailLines}`,
`MAX_LOG_BYTES=${policy.maxLogBytes}`,
`MAX_MESSAGE_BYTES=${policy.maxMessageBytes}`,
`MAX_CONTAINERS=${policy.maxContainers}`,
"export TEKTON_NAMESPACE TASKRUN_QUERY PIPELINE_RUN_NAME PIPELINE_RUN_PREFIX LOGS_TAIL_LINES MAX_LOG_BYTES MAX_MESSAGE_BYTES MAX_CONTAINERS",
"node \"$tmpdir/taskrun-drilldown.mjs\"",
].join("\n");
const startedAt = Date.now();
const result = runKubeScript(registry, options, script, "", policy.taskRunTimeoutSeconds * 1000);
const parsed = result.exitCode === 0 ? parseJsonObject(result.stdout) : null;
return {
ok: result.exitCode === 0 && parsed !== null && parsed.ok !== false,
action: "taskrun",
follower: follower.id,
adapter: follower.adapter,
statusAuthority: options.inCluster ? "kubernetes-api-serviceaccount" : "target-node-kubectl-raw",
parsedDownstreamCliOutput: false,
query: {
taskRun,
pipelineRun: options.pipelineRunName,
tektonNamespace: follower.nativeStatus.tekton.namespace,
pipelineRunPrefix: follower.nativeStatus.tekton.pipelineRunPrefix,
},
policy,
result: parsed,
command: {
exitCode: result.exitCode,
timedOut: result.timedOut,
elapsedMs: Date.now() - startedAt,
stderrTail: result.exitCode === 0 ? "" : redactText(tailText(result.stderr || result.stdout, 1200)),
},
next: {
status: `bun scripts/cli.ts cicd branch-follower status --follower ${follower.id}`,
taskRunJson: `bun scripts/cli.ts cicd branch-follower status --follower ${follower.id} --taskrun ${taskRun} --logs-tail ${policy.logsTailLines} --json`,
},
};
}
function parseJsonObject(text: string): Record<string, unknown> | null {
const trimmed = text.trim();
if (trimmed.length === 0) return null;
try {
const parsed = JSON.parse(trimmed) as unknown;
return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
} catch {
return null;
}
}
function tailText(text: string, maxChars: number): string {
return text.length <= maxChars ? text : text.slice(text.length - maxChars);
}
+12 -1
View File
@@ -2,7 +2,7 @@
// Responsibility: type contracts shared by branch follower entry, controller render, and native K8s helpers.
export type OutputMode = "human" | "json" | "yaml";
export type BranchFollowerAction = "help" | "plan" | "apply" | "status" | "run-once" | "debug-step" | "cleanup-state" | "events" | "logs";
export type BranchFollowerAction = "help" | "plan" | "apply" | "status" | "run-once" | "debug-step" | "cleanup-state" | "events" | "logs" | "taskrun";
export type BranchFollowerDebugStep = "state-read" | "controller-source" | "status-read" | "decide" | "state-write";
export type BranchFollowerPhase =
| "Observed"
@@ -31,6 +31,10 @@ export interface ParsedOptions {
raw: boolean;
recordState: boolean;
debugStep: BranchFollowerDebugStep | null;
taskRunName: string | null;
pipelineRunName: string | null;
logsTailLines: number | null;
maxLogBytes: number | null;
output: OutputMode;
limit: number;
tailBytes: number;
@@ -79,6 +83,13 @@ export interface FollowerSpec {
logs: CommandSpec;
};
nativeStatus: NativeStatusSpec;
drillDown: {
taskRunTimeoutSeconds: number;
logsTailLines: number;
maxLogBytes: number;
maxMessageBytes: number;
maxContainers: number;
};
closeoutChecks: string[];
}