@lchase/kiln 0.1.0 → 0.4.0

package/dist/report.js

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
+import { readBoardFiles, readReviewRounds } from "./board.js";
+import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { inFlightCount, isDone, isLanded, jobState, } from "./reconcile.js";
 export function shellQuote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;
@@ -28,105 +30,294 @@ export function gateAnswerCommand(checkout, runId, gate, choice, title) {
     const titlePrefix = title ? `KILN_TASK_TITLE=${shellQuote(title)} ` : "";
     return `cd ${shellQuote(checkout)} && mkdir -p ${pendingDir} && printf '%s\\n' ${shellQuote(answer)} > ${answerFile} && ${titlePrefix}${yakInvocation("resume", runId)}`;
 }
-export function renderStatus(observation, jobId) {
-    const jobs = jobId ? observation.jobs.filter((job) => job.jobId === jobId) : observation.jobs;
-    if (jobId && jobs.length === 0) {
+/**
+ * Mark a workflow's leaf steps from yak journal events.
+ * A later `step.started` reopens a step that already completed (the next loop round).
+ * Events whose id is not in the plan are ignored when the plan is non-empty,
+ * so a loop container does not sit beside its body. An empty plan uses
+ * first-seen event order.
+ */
+export function stepProgress(plan, events) {
+    const order = [...plan];
+    const phase = new Map();
+    for (const id of order)
+        phase.set(id, "pending");
+    for (const event of events) {
+        if (!event.stepId)
+            continue;
+        if (!phase.has(event.stepId)) {
+            if (plan.length > 0)
+                continue;
+            order.push(event.stepId);
+            phase.set(event.stepId, "pending");
+        }
+        if (event.t === "step.started")
+            phase.set(event.stepId, "current");
+        else if (event.t === "step.completed")
+            phase.set(event.stepId, "done");
+        else if (event.t === "step.failed")
+            phase.set(event.stepId, "failed");
+    }
+    return order.map((id) => ({ id, phase: phase.get(id) ?? "pending" }));
+}
+/** Detail of the latest step that failed and has not started or completed since. */
+export function latestStepFailure(events) {
+    const settled = new Set();
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (!event)
+            continue;
+        if (event.t === "step.started" || event.t === "step.completed") {
+            settled.add(event.stepId);
+            continue;
+        }
+        if (event.t === "step.failed" && !settled.has(event.stepId) && event.detail)
+            return event.detail;
+    }
+    return undefined;
+}
+/**
+ * Derived state for every job, or for one id.
+ * Throws `No job <id>` when that id is not on disk, same as `kiln status`.
+ */
+export function statusView(observation, jobId) {
+    const selected = jobId ? observation.jobs.filter((job) => job.jobId === jobId) : observation.jobs;
+    if (jobId && selected.length === 0) {
         throw new Error(`No job ${jobId}.`);
     }
-    if (jobs.length === 0)
+    return { jobs: selected.map((job) => toStatusJob(job, observation)) };
+}
+export function renderStatus(view) {
+    if (view.jobs.length === 0)
         return "no jobs\n";
     const lines = [];
-    for (const job of jobs) {
-        if (job.error) {
-            lines.push(`${job.jobId}  invalid: ${job.error}`);
+    for (const job of view.jobs) {
+        lines.push(statusHeader(job));
+        if (job.state === "invalid")
             continue;
+        for (const detail of statusDetails(job))
+            lines.push(`  ${detail}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Extra lines `kiln status` prints under the job header, without the indent. */
+export function statusDetails(job) {
+    const lines = [];
+    if (job.source)
+        lines.push(`source ${job.source.kind} ${job.source.ref}`);
+    if (job.findingsPath)
+        lines.push(`findings ${job.findingsPath}`);
+    else if (job.workflow === INVESTIGATION_WORKFLOW && job.state === "done")
+        lines.push("findings missing");
+    if (job.prPending)
+        lines.push("pull request not opened yet");
+    if (job.state === "failed" && job.deliveryError)
+        lines.push(job.deliveryError);
+    if (job.state === "failed" && job.prClosedUnmerged && job.prNumber) {
+        lines.push(`pull request #${job.prNumber} was closed without merging`);
+    }
+    if (job.viewError && (job.state === "in-review" || job.state === "done")) {
+        lines.push(`could not read pull request: ${job.viewError}`);
+    }
+    if (job.state === "failed" && job.launchFailed && job.logPath)
+        lines.push(`log ${job.logPath}`);
+    if (job.state === "failed" && job.launchError)
+        lines.push(job.launchError);
+    if (job.ledgerError)
+        lines.push(job.ledgerError);
+    if (job.attemptCount > 0)
+        lines.push(`attempts ${job.attemptCount}`);
+    if (job.lastFailureReason)
+        lines.push(`reason ${job.lastFailureReason}`);
+    if (job.nextRetryAt)
+        lines.push(`next retry ${job.nextRetryAt}`);
+    if (job.state === "dead" && job.attemptCount > 0)
+        lines.push(`retry: kiln retry ${job.jobId}`);
+    if (job.noReadableApproval)
+        lines.push("no readable approval decision");
+    if (job.cancelCommand)
+        lines.push(job.cancelCommand);
+    if (job.state === "blocked") {
+        for (const dep of job.dependsOn) {
+            if (dep.blockedDetail)
+                lines.push(dep.blockedDetail);
         }
-        const state = jobState(job, observation);
-        const run = job.run ? `  run ${job.run.runId}` : "";
-        const branch = job.run && (state === "done" || state === "in-review") ? `  branch yak/${job.run.runId}` : "";
-        const pr = prSuffix(job, state);
-        lines.push(`${job.jobId}  ${job.repo}  ${job.workflow}  ${state}${run}${branch}${pr}`);
-        if (job.source)
-            lines.push(`  source ${job.source.kind} ${job.source.ref}`);
-        if (state === "in-review" && !job.delivery?.prNumber) {
-            lines.push("  pull request not opened yet");
-        }
-        if (state === "failed" && job.delivery?.error) {
-            lines.push(`  ${job.delivery.error}`);
-        }
-        if (state === "failed" && job.delivery?.prState === "CLOSED" && job.delivery.prNumber) {
-            lines.push(`  pull request #${job.delivery.prNumber} was closed without merging`);
-        }
-        if (job.delivery?.viewError && (state === "in-review" || state === "done")) {
-            lines.push(`  could not read pull request: ${job.delivery.viewError}`);
-        }
-        if (state === "failed" && job.launchFailed && job.logPath) {
-            lines.push(`  log ${job.logPath}`);
-        }
-        if (state === "failed" && job.launchError) {
-            lines.push(`  ${job.launchError}`);
-        }
-        if (state === "failed" && job.run?.status === "ok" && !job.run.gateDecision) {
-            lines.push("  no readable approval decision");
-        }
-        if (state === "dead" && job.run) {
-            lines.push(`  fix: cd ${shellQuote(job.run.checkout)} && ${yakInvocation("cancel", job.run.runId)}`);
-        }
-        if (state === "blocked") {
-            for (const line of blockedLines(job, observation))
-                lines.push(line);
-        }
-        if (state === "needs-human" && job.run) {
-            for (const gate of job.run.gates) {
-                lines.push(`  gate ${gate.stepId}: ${gate.prompt}`);
-                appendGateCommands(lines, job, gate);
-            }
+    }
+    if (job.state === "needs-human") {
+        for (const gate of job.gates) {
+            lines.push(`gate ${gate.stepId}: ${gate.prompt}`);
+            if (gate.choices.includes("approve"))
+                lines.push(`approve: kiln approve ${job.jobId}`);
+            if (gate.choices.includes("reject"))
+                lines.push(`reject: kiln reject ${job.jobId}`);
         }
     }
-    return `${lines.join("\n")}\n`;
+    return lines;
 }
-function prSuffix(job, state) {
-    const url = job.delivery?.prUrl;
-    if (!url)
-        return "";
-    if (state !== "in-review" && state !== "done" && state !== "failed")
-        return "";
-    return `  pr ${url}`;
+function statusHeader(job) {
+    if (job.state === "invalid")
+        return `${job.jobId}  invalid: ${job.invalidReason ?? "invalid"}`;
+    const run = job.runId ? `  run ${job.runId}` : "";
+    const branch = job.branch ? `  branch ${job.branch}` : "";
+    const pr = job.prUrl && (job.state === "in-review" || job.state === "done" || job.state === "failed")
+        ? `  pr ${job.prUrl}`
+        : "";
+    return `${job.jobId}  ${job.repo}  ${job.workflow}  ${job.state}${run}${branch}${pr}`;
 }
-function blockedLines(job, observation) {
-    const lines = [];
+function toStatusJob(job, observation) {
+    if (job.error) {
+        return {
+            jobId: job.jobId,
+            title: job.title,
+            repo: job.repo,
+            workflow: job.workflow,
+            state: "invalid",
+            dependsOn: dependencyViews(job, observation),
+            stack: job.stack === true,
+            ...(job.source ? { source: { kind: job.source.kind, ref: job.source.ref } } : {}),
+            ...(job.specPath ? { specPath: job.specPath } : {}),
+            ...(job.logPath ? { logPath: job.logPath } : {}),
+            ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+            launchFailed: job.launchFailed,
+            attemptCount: job.attemptCount ?? 0,
+            maxAttempts: observation.maxAttempts,
+            ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
+            ...(job.nextRetryAt ? { nextRetryAt: job.nextRetryAt } : {}),
+            invalidReason: job.error,
+            prPending: false,
+            prClosedUnmerged: false,
+            noReadableApproval: false,
+            gates: [],
+            canApprove: false,
+            canReject: false,
+            steps: progressFor(job),
+            ...(job.createdAt ? { createdAt: job.createdAt } : {}),
+            ...(job.logTail ? { logTail: job.logTail } : {}),
+            ...boardFields(job),
+        };
+    }
+    const state = jobState(job, observation);
+    const gates = state === "needs-human" && job.run ? job.run.gates.map(toGateView) : [];
+    const prNumber = job.delivery?.prNumber;
+    const runId = job.run?.runId;
+    const showBranch = (state === "done" || state === "in-review") && runId !== undefined;
+    const failureDetail = job.run?.stepEvents ? latestStepFailure(job.run.stepEvents) : undefined;
+    return {
+        jobId: job.jobId,
+        title: job.title,
+        repo: job.repo,
+        workflow: job.workflow,
+        state,
+        dependsOn: dependencyViews(job, observation),
+        stack: job.stack === true,
+        ...(job.source ? { source: { kind: job.source.kind, ref: job.source.ref } } : {}),
+        ...(runId ? { runId } : {}),
+        ...(showBranch ? { branch: `yak/${runId}` } : {}),
+        ...(job.delivery?.prUrl ? { prUrl: job.delivery.prUrl } : {}),
+        ...(prNumber ? { prNumber } : {}),
+        ...(job.logPath ? { logPath: job.logPath } : {}),
+        ...(job.specPath ? { specPath: job.specPath } : {}),
+        ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+        launchFailed: job.launchFailed,
+        attemptCount: job.attemptCount ?? 0,
+        maxAttempts: observation.maxAttempts,
+        ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
+        ...(job.nextRetryAt && !job.retriesExhausted ? { nextRetryAt: job.nextRetryAt } : {}),
+        ...(job.ledgerError ? { ledgerError: job.ledgerError } : {}),
+        ...(job.launchError ? { launchError: job.launchError } : {}),
+        ...(job.delivery?.error ? { deliveryError: job.delivery.error } : {}),
+        ...(job.delivery?.viewError ? { viewError: job.delivery.viewError } : {}),
+        prPending: state === "in-review" && !prNumber,
+        prClosedUnmerged: job.delivery?.prState === "CLOSED",
+        noReadableApproval: state === "failed" && job.run?.status === "ok" && !job.run.gateDecision,
+        ...(job.run && (job.run.status === "dead" || state === "dead")
+            ? { cancelCommand: `fix: cd ${shellQuote(job.run.checkout)} && ${yakInvocation("cancel", job.run.runId)}` }
+            : {}),
+        gates,
+        canApprove: gates.some((gate) => gate.choices.includes("approve")),
+        canReject: gates.some((gate) => gate.choices.includes("reject")),
+        steps: progressFor(job),
+        ...(job.createdAt ? { createdAt: job.createdAt } : {}),
+        ...(job.run?.startedAt ? { startedAt: job.run.startedAt } : {}),
+        ...(job.run?.finishedAt ? { finishedAt: job.run.finishedAt } : {}),
+        ...(job.logTail ? { logTail: job.logTail } : {}),
+        ...(job.diffSummary ? { diffSummary: job.diffSummary } : {}),
+        ...(failureDetail ? { failureDetail } : {}),
+        ...boardFields(job),
+    };
+}
+function boardFields(job) {
+    const runDir = job.run ? join(job.run.checkout, ".runs", job.run.runId) : undefined;
+    const rounds = readReviewRounds(runDir);
+    const files = readBoardFiles({
+        ...(runDir ? { runDir } : {}),
+        ...(job.specPath ? { specPath: job.specPath } : {}),
+        ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+        ...(job.workflow !== INVESTIGATION_WORKFLOW && job.diffSummary ? { diffSummary: job.diffSummary } : {}),
+        ...(job.logTail ? { logTail: job.logTail } : {}),
+        ...(job.workflow ? { workflow: job.workflow } : {}),
+        gates: job.run?.gates ?? [],
+    });
+    return {
+        ...(rounds.length > 0 ? { rounds } : {}),
+        ...(files.length > 0 ? { files } : {}),
+    };
+}
+function progressFor(job) {
+    const plan = job.run?.stepPlan?.length ? job.run.stepPlan : (job.stepPlan ?? []);
+    return stepProgress(plan, job.run?.stepEvents ?? []);
+}
+function toGateView(gate) {
+    const choices = gate.choices?.length ? gate.choices : ["approve", "reject"];
+    return {
+        stepId: gate.stepId,
+        prompt: gate.prompt,
+        ...(gate.rendered ? { rendered: gate.rendered } : {}),
+        choices,
+        artifacts: gate.artifacts ?? [],
+        reviews: gate.reviews ?? [],
+    };
+}
+function dependencyViews(job, observation) {
+    const reasons = blockReasons(job, observation);
+    return job.dependsOn.map((dep) => {
+        const upstream = observation.jobs.find((candidate) => candidate.jobId === dep);
+        const state = !upstream ? "missing" : upstream.error ? "invalid" : jobState(upstream, observation);
+        const blockedDetail = reasons.find((reason) => reason.dep === dep)?.detail;
+        return {
+            jobId: dep,
+            state,
+            ...(blockedDetail ? { blockedDetail } : {}),
+        };
+    });
+}
+function blockReasons(job, observation) {
+    const reasons = [];
     for (const dep of job.dependsOn) {
         const upstream = observation.jobs.find((candidate) => candidate.jobId === dep);
         if (!upstream) {
-            lines.push(`  blocked on missing job ${dep}`);
+            reasons.push({ dep, detail: `blocked on missing job ${dep}` });
             continue;
         }
         if (job.stack) {
             if (!isLanded(upstream))
-                lines.push(`  waiting for ${dep} to land`);
+                reasons.push({ dep, detail: `waiting for ${dep} to land` });
             continue;
         }
         if (isDone(upstream))
             continue;
         const number = upstream.delivery?.prNumber;
         if (number && !upstream.delivery?.merged && upstream.delivery?.prState !== "CLOSED") {
-            lines.push(`  waiting for PR #${number} to merge`);
+            reasons.push({ dep, detail: `waiting for PR #${number} to merge` });
             continue;
         }
         if ((upstream.deliver ?? "local") === "pr" && isLanded(upstream)) {
-            lines.push(`  waiting for ${dep} to open a pull request`);
+            reasons.push({ dep, detail: `waiting for ${dep} to open a pull request` });
         }
     }
-    return lines;
-}
-function appendGateCommands(lines, job, gate) {
-    const choices = gate.choices?.length ? gate.choices : ["approve", "reject"];
-    if (choices.includes("approve"))
-        lines.push(`  approve: kiln approve ${job.jobId}`);
-    if (choices.includes("reject"))
-        lines.push(`  reject: kiln reject ${job.jobId}`);
+    return reasons;
 }
-export function renderTick(observation, actions, launches, delivers = []) {
+export function renderTick(observation, actions, launches, delivers = [], findings = [], notes = []) {
     const lines = [`tick  inFlight=${inFlightCount(observation)}  maxConcurrent=${observation.maxConcurrent}`];
     for (const job of observation.jobs) {
         if (job.error)
@@ -141,16 +332,26 @@ export function renderTick(observation, actions, launches, delivers = []) {
             ? `deliver ${deliver.jobId}  ${deliver.repo}  ${deliver.detail}`
             : `deliver ${deliver.jobId}  ${deliver.repo}  failed: ${deliver.detail}`);
     }
+    for (const recorded of findings) {
+        lines.push(recorded.status === "wrote"
+            ? `findings ${recorded.jobId}  ${recorded.path}`
+            : `findings ${recorded.jobId}  missing`);
+    }
+    for (const note of notes) {
+        const next = note.nextRetryAt ? `  next ${note.nextRetryAt}` : "  dead";
+        lines.push(`${note.kind} ${note.jobId}  ${note.reason}  attempt ${note.attempt}${next}`);
+    }
     for (const launch of launches) {
-        lines.push(`launch ${launch.jobId}  ${launch.repo}`);
+        lines.push(`${launch.retry ? "retry" : "launch"} ${launch.jobId}  ${launch.repo}`);
         for (const line of launch.output.split("\n")) {
             if (line.trim())
                 lines.push(`  ${line}`);
         }
     }
-    if (!actions.some((action) => action.type === "launch") &&
+    if (!actions.some((action) => action.type === "launch" || action.type === "retry") &&
         launches.length === 0 &&
-        delivers.length === 0) {
+        delivers.length === 0 &&
+        findings.length === 0) {
         lines.push("nothing to launch");
     }
     return `${lines.join("\n")}\n`;

package/dist/schemas.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 /**
  * Kiln config file. `repos` is an open map: any name, not a fixed set.
- * `path` is absolute, relative to the config file's directory, or `~`.
+ * `path` is absolute, `~`, or (in older files) relative to the config directory.
+ * `repo add` stores a relative path as absolute, resolved from the working directory.
  * `test` is the shell command a workflow runs as its verify step (`KILN_TEST`).
  */
 /**
@@ -25,9 +26,20 @@ export const JiraConfigSchema = z.object({
     email: z.string().optional(),
     apiToken: z.string().optional(),
 });
+/** No yak event and no log output for this long stalls a running job. `<= 0` disables it. */
+export const DEFAULT_STALL_TIMEOUT_MS = 15 * 60 * 1000;
+/** Transient failures retry until this many attempts, then the job is dead. */
+export const DEFAULT_MAX_ATTEMPTS = 3;
 export const KilnConfigFileSchema = z.object({
     note: z.string().min(1).optional(),
     maxConcurrent: z.number().int().min(1).optional(),
+    /**
+     * Milliseconds without a yak event or log output before a running job is
+     * killed and retried. Default 15 minutes. `0` or negative disables stall detection.
+     */
+    stallTimeoutMs: z.number().int().optional(),
+    /** Transient failures before the job is dead. Default 3. */
+    maxAttempts: z.number().int().min(1).optional(),
     adapter: z.enum(["mock", "claude-code"]).optional(),
     repos: z.record(z.string(), RepoEntrySchema),
     jira: JiraConfigSchema.optional(),
@@ -59,6 +71,8 @@ export const JobSchema = z.object({
      * When true, this job starts once its single upstream has landed, on that
      * upstream's branch. Omitted means after-merged: wait until every upstream
      * is `done`. More than one `dependsOn` with `stack` is rejected at add time.
+     * Stacking onto an investigation is rejected: that workflow does not land
+     * a branch.
      */
     stack: z.boolean().optional(),
     source: JobSourceSchema.optional(),
@@ -71,10 +85,14 @@ export const JobSchema = z.object({
  * For `deliver=local`, `done` is a run that finished ok with an approve
  * decision. For `deliver=pr`, `done` is that landed run whose pull request
  * has merged (`state` or `mergedAt`, so a squash merge counts). `in-review`
- * is the landed run while the pull request is still open. A reject, a
- * failure, a dead process, and an ok run with no readable approval do not
- * unblock an after-merged dependent. A stacked job unblocks when its one
- * upstream has landed, which includes `in-review`.
+ * is the landed run while the pull request is still open. An investigation
+ * is `done` when the gate says approve, including when the repo is
+ * `deliver=pr`. It does not enter `in-review`. A reject, a failure, a dead
+ * process, and an ok run with no readable approval do not unblock an
+ * after-merged dependent. A stacked job unblocks when its one upstream has
+ * landed, which includes `in-review`. `dead` is also a job whose transient
+ * failures have used `maxAttempts`. Those attempts live under the kiln
+ * directory, not in this file.
  */
 export const JOB_STATES = [
     "queued",