@lchase/kiln 0.12.0 → 0.14.0

package/dist/triggers.js

@@ -1,12 +1,16 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { loadKilnConfig } from "./config.js";
 import { appendEvent, readEvents } from "./events.js";
 import { isIgnoredAuthor } from "./feedback.js";
+import { DEFAULT_REVIEW_LABEL } from "./host.js";
 import { searchJiraIssues } from "./intake/jira.js";
 import { listValidJobs, writeJob } from "./jobs.js";
+import { jobBasename } from "./paths.js";
 import { pausedFrom, spendSnapshot } from "./rails.js";
 import { redact } from "./redact.js";
+import { isPidAlive } from "./reliability.js";
 import { ISSUE_KEY } from "./schemas.js";
 import { REVIEW_WORKFLOW } from "./workflow.js";
 /**
@@ -14,7 +18,8 @@ import { REVIEW_WORKFLOW } from "./workflow.js";
  * A trigger writes a typed event. The router creates a job or attaches to
  * one. The dedupe key lives on that event, so a restart does not create
  * the job twice. A failed fire records `last_error` and waits for the next
- * slot. Pause and the daily cap record a skip. Nothing is queued.
+ * slot. Pause, the daily cap, and the review burst caps record a skip.
+ * Nothing over the cap is queued.
  *
  * Jira is polled. `jiraIssueEvent` is the seam a webhook can call later.
  * Pull-request activity reuses the feedback loop's snapshot. It does not
@@ -25,8 +30,20 @@ export const PR_ACTIVITY_TRIGGER = "pr-activity";
 /** Minute 0 of every hour, local time. */
 export const DEFAULT_REVIEW_CRON = "0 * * * *";
 export const DEFAULT_JIRA_EVERY = "5m";
+/** New review jobs one fire may create. Further pull requests are skipped. */
+export const DEFAULT_REVIEW_MAX_NEW = 3;
+/** Queued or running review jobs at once. A review waiting in the Inbox does not count. */
+export const DEFAULT_REVIEW_MAX_QUEUED = 5;
 const BUILTIN_TRIGGERS = [
-    { id: REVIEW_REQUESTS_TRIGGER, kind: "schedule", cron: DEFAULT_REVIEW_CRON, enabled: true },
+    {
+        id: REVIEW_REQUESTS_TRIGGER,
+        kind: "schedule",
+        cron: DEFAULT_REVIEW_CRON,
+        enabled: true,
+        label: DEFAULT_REVIEW_LABEL,
+        maxNew: DEFAULT_REVIEW_MAX_NEW,
+        maxQueued: DEFAULT_REVIEW_MAX_QUEUED,
+    },
     { id: PR_ACTIVITY_TRIGGER, kind: "pr", enabled: true },
 ];
 const BUILTIN_ROUTES = [
@@ -34,6 +51,16 @@ const BUILTIN_ROUTES = [
     { id: PR_ACTIVITY_TRIGGER, trigger: PR_ACTIVITY_TRIGGER, action: "attach" },
 ];
 const REVIEW_REF = /^review:([^:]+):(\d+):([0-9a-f]{7,64})$/i;
+/** `review:<repo>:<number>:<head sha>` from a review-request job. SHA is lowercase. */
+export function parseReviewSource(ref) {
+    const match = REVIEW_REF.exec(ref);
+    const repo = match?.[1];
+    const number = Number(match?.[2]);
+    const sha = match?.[3]?.toLowerCase();
+    if (!repo || !sha || !Number.isInteger(number) || number <= 0)
+        return undefined;
+    return { repo, number, sha };
+}
 export function effectiveTriggers(file) {
     const byId = new Map();
     for (const trigger of BUILTIN_TRIGGERS)
@@ -234,7 +261,7 @@ export function jiraIssueEvent(triggerId, repo, issue) {
 export function reviewHeadOf(job) {
     if (job.workflow !== REVIEW_WORKFLOW || job.source?.kind !== "trigger")
         return undefined;
-    return REVIEW_REF.exec(job.source.ref)?.[3];
+    return parseReviewSource(job.source.ref)?.sha;
 }
 /** Download the pull request head when the checkout does not have that commit yet. */
 export function ensureReviewHead(checkout, prNumber, sha) {
@@ -304,11 +331,21 @@ export function triggerRows(config, events, now = new Date()) {
             event: event.event,
             summary: triggerSummary(event),
         }));
+        const review = trigger.id === REVIEW_REQUESTS_TRIGGER;
+        const repoLabels = review ? repoReviewLabels(config) : [];
         return {
             id: trigger.id,
             kind: trigger.kind,
             enabled: trigger.enabled !== false,
             schedule: scheduleLabel(trigger),
+            ...(review
+                ? {
+                    label: reviewRequestLabel(trigger),
+                    maxNew: reviewMaxNew(trigger),
+                    maxQueued: reviewMaxQueued(trigger),
+                    ...(repoLabels.length > 0 ? { repoLabels } : {}),
+                }
+                : {}),
             ...(nextFire(trigger, state, now) ? { nextFire: nextFire(trigger, state, now) } : {}),
             ...(state?.lastFire && Number.isFinite(Date.parse(state.lastFire)) ? { lastFire: state.lastFire } : {}),
             ...(state?.lastError ? { lastError: state.lastError } : {}),
@@ -336,14 +373,21 @@ function runSchedule(input, trigger, routes, now, startup) {
     if (reviews) {
         if (!input.reviews)
             return;
+        // A disable that landed after this process started, including during the
+        // startup list, must not create jobs. The Triggers page reads the file,
+        // so it can already say disabled while this fire is still in the list.
+        if (!triggerEnabledNow(input.config, trigger.id))
+            return;
         let requests;
         try {
-            requests = input.reviews.list(Object.entries(input.config.repos).map(([name, repo]) => ({ name, path: repo.path })));
+            requests = input.reviews.list(reviewTargets(input.config, trigger));
         }
         catch (error) {
             failSlot(input.config, trigger.id, stamp, errorMessage(error), now);
             return;
         }
+        if (!triggerEnabledNow(input.config, trigger.id))
+            return;
         succeedSlot(input.config.kilnDir, trigger.id, stamp);
         appendFire(input.config, {
             key: `schedule:${trigger.id}:${stamp}`,
@@ -352,17 +396,40 @@ function runSchedule(input, trigger, routes, now, startup) {
             id: stamp,
             revision: stamp,
         });
+        const maxNew = reviewMaxNew(trigger);
+        const maxQueued = reviewMaxQueued(trigger);
+        let created = 0;
+        let active = reviewSlotsInUse(input.config);
         for (const request of requests) {
+            if (!triggerEnabledNow(input.config, trigger.id))
+                break;
+            const key = reviewDedupeKey(request);
+            if (reviewDrafted(input.config, key)) {
+                try {
+                    ingestReview(input.config, request, routes, now);
+                }
+                catch (error) {
+                    noteReviewFailure(input.config, trigger.id, stamp, request, error, now);
+                }
+                continue;
+            }
+            if (active >= maxQueued) {
+                noteSkip(input.config, trigger.id, "queued-cap", stamp, now, key);
+                continue;
+            }
+            if (created >= maxNew) {
+                noteSkip(input.config, trigger.id, "burst-cap", stamp, now, key);
+                continue;
+            }
             try {
-                ingestReview(input.config, request, routes, now);
+                const outcome = ingestReview(input.config, request, routes, now);
+                if (outcome === "created") {
+                    created += 1;
+                    active += 1;
+                }
             }
             catch (error) {
-                remember(input.config.kilnDir, trigger.id, {
-                    lastFire: stamp,
-                    lastError: publicError(errorMessage(error)),
-                    lastErrorAt: now.toISOString(),
-                });
-                appendFailed(input.config, trigger.id, publicError(errorMessage(error)), `review:${request.repo}:${request.number}`, now);
+                noteReviewFailure(input.config, trigger.id, stamp, request, error, now);
             }
         }
         return;
@@ -390,8 +457,8 @@ function ingestReview(config, request, routes, now) {
     const base = repo.base ?? "the default branch";
     const url = httpUrl(request.url);
     const title = oneLine(request.title) || `PR ${request.number}`;
-    ingest(config, {
-        key: `review:${request.repo}:${request.number}:${sha}`,
+    return ingest(config, {
+        key: reviewDedupeKey(request),
         source: "review",
         triggerId: REVIEW_REQUESTS_TRIGGER,
         id: String(request.number),
@@ -455,20 +522,20 @@ function ingest(config, event, routes, now) {
     const routed = routedKeys(events);
     const decision = routeTrigger(event, routes, routed);
     if (decision.type === "ignore" || decision.type === "deduped")
-        return;
+        return "ignored";
     if (decision.type === "unrouted") {
         noteConfigError(config, event.triggerId, `No route for trigger ${event.triggerId}.`, now);
-        return;
+        return "ignored";
     }
     appendFire(config, event, now);
     if (decision.type === "attach") {
         appendRouted(config, event, decision.jobId, "attach", undefined, now);
-        return;
+        return "existing";
     }
     const existing = listValidJobs(config).find((job) => job.source?.kind === "trigger" && job.source.ref === event.key);
     if (existing) {
         appendRouted(config, event, existing.id, "create", decision.workflow, now);
-        return;
+        return "existing";
     }
     const title = oneLine(event.title ?? "") || event.id;
     const specText = redact(event.body?.trim() || `# ${title}\n`);
@@ -484,13 +551,14 @@ function ingest(config, event, routes, now) {
         now,
     });
     appendRouted(config, event, written.job.id, "create", decision.workflow, now);
+    return "created";
 }
 function reviewSpec(input) {
     const lines = [`# Draft review: ${input.title}`, ""];
     if (input.url)
         lines.push(`Pull request: ${input.url}`);
     lines.push(`Number: ${input.number}`, `Head: ${input.sha}`, `Base: ${input.base}`, "");
-    lines.push("Read the change and return a draft review.", "Do not post, approve, merge, or push.", "Approving the gate keeps the draft. Kiln does not post it to GitHub.", "");
+    lines.push("Read the change and return a draft review.", "Do not post, approve, merge, or push.", "Approving the gate posts this draft as a pull request comment. Kiln does not approve the pull request or merge it.", "");
     return lines.join("\n");
 }
 function appendFire(config, event, now) {
@@ -545,7 +613,7 @@ function failSlot(config, triggerId, stamp, message, now) {
 function succeedSlot(kilnDir, triggerId, stamp) {
     remember(kilnDir, triggerId, { lastFire: stamp, lastError: undefined, lastErrorAt: undefined });
 }
-function noteSkip(config, triggerId, reason, stamp, now) {
+function noteSkip(config, triggerId, reason, stamp, now, externalId) {
     appendEvent(config.kilnDir, {
         job_id: null,
         event: "trigger.skipped",
@@ -553,10 +621,21 @@ function noteSkip(config, triggerId, reason, stamp, now) {
         properties: {
             trigger_id: triggerId,
             reason,
-            once: `skipped:${triggerId}:${stamp}:${reason}`,
+            ...(externalId ? { external_id: externalId } : {}),
+            once: externalId
+                ? `skipped:${triggerId}:${stamp}:${reason}:${externalId}`
+                : `skipped:${triggerId}:${stamp}:${reason}`,
         },
     });
 }
+function noteReviewFailure(config, triggerId, stamp, request, error, now) {
+    remember(config.kilnDir, triggerId, {
+        lastFire: stamp,
+        lastError: publicError(errorMessage(error)),
+        lastErrorAt: now.toISOString(),
+    });
+    appendFailed(config, triggerId, publicError(errorMessage(error)), `review:${request.repo}:${request.number}`, now);
+}
 function noteConfigError(config, triggerId, message, now) {
     const error = publicError(message);
     const current = readRuntime(config.kilnDir)[triggerId];
@@ -565,6 +644,133 @@ function noteConfigError(config, triggerId, message, now) {
     remember(config.kilnDir, triggerId, { lastError: error, lastErrorAt: now.toISOString() });
     appendFailed(config, triggerId, error, `config:${error}`, now);
 }
+/** GitHub label for a review-requests fire. Omitted config uses {@link DEFAULT_REVIEW_LABEL}. */
+export function reviewRequestLabel(trigger) {
+    return trigger.label?.trim() || DEFAULT_REVIEW_LABEL;
+}
+export function reviewMaxNew(trigger) {
+    return trigger.maxNew ?? DEFAULT_REVIEW_MAX_NEW;
+}
+export function reviewMaxQueued(trigger) {
+    return trigger.maxQueued ?? DEFAULT_REVIEW_MAX_QUEUED;
+}
+/**
+ * Review jobs that are queued or running.
+ * A review sitting on the Inbox gate has a finished journal and does not count.
+ * A cancelled job does not count.
+ */
+export function reviewSlotsInUse(config) {
+    let count = 0;
+    for (const job of listValidJobs(config)) {
+        if (job.workflow !== REVIEW_WORKFLOW || job.cancelledAt)
+            continue;
+        if (reviewOccupiesSlot(config, job))
+            count += 1;
+    }
+    return count;
+}
+function reviewTargets(config, trigger) {
+    const fallback = reviewRequestLabel(trigger);
+    return Object.entries(config.repos).map(([name, repo]) => ({
+        name,
+        path: repo.path,
+        label: repo.reviewLabel?.trim() || fallback,
+    }));
+}
+function repoReviewLabels(config) {
+    const labels = [];
+    for (const [repo, entry] of Object.entries(config.repos)) {
+        const label = entry.reviewLabel?.trim();
+        if (label)
+            labels.push({ repo, label });
+    }
+    return labels;
+}
+function reviewDedupeKey(request) {
+    return `review:${request.repo}:${request.number}:${request.headSha.trim().toLowerCase()}`;
+}
+function reviewDrafted(config, key) {
+    if (routedKeys(readEvents(config.kilnDir, { warn: () => { } })).has(key))
+        return true;
+    return listValidJobs(config).some((job) => job.source?.kind === "trigger" && job.source.ref === key);
+}
+/**
+ * True when the trigger is enabled in memory and on disk.
+ * The disk read catches a disable that arrived while `gh pr list` or a fetch was running.
+ */
+function triggerEnabledNow(config, id) {
+    if (!triggerIsEnabled(config.triggers, id))
+        return false;
+    try {
+        return triggerIsEnabled(loadKilnConfig(config.configPath).triggers, id);
+    }
+    catch {
+        return true;
+    }
+}
+function triggerIsEnabled(file, id) {
+    const trigger = effectiveTriggers(file).find((item) => item.id === id);
+    return trigger?.enabled !== false;
+}
+function reviewOccupiesSlot(config, job) {
+    if (launchingAlive(config.kilnDir, job.id))
+        return true;
+    const repo = config.repos[job.repo];
+    if (!repo)
+        return true;
+    const runs = journalsForJob(repo.path, job.id);
+    if (runs.length === 0)
+        return !deadLaunch(config.kilnDir, job.id);
+    return runs.some((run) => !run.finished);
+}
+function launchingAlive(kilnDir, jobId) {
+    const path = join(kilnDir, "launching", `${jobBasename(jobId)}.json`);
+    if (!existsSync(path))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed.pid === "number" && isPidAlive(parsed.pid);
+    }
+    catch {
+        return false;
+    }
+}
+function deadLaunch(kilnDir, jobId) {
+    const path = join(kilnDir, "launching", `${jobBasename(jobId)}.json`);
+    if (!existsSync(path))
+        return false;
+    return !launchingAlive(kilnDir, jobId);
+}
+function journalsForJob(checkout, jobId) {
+    const runsDir = join(checkout, ".runs");
+    if (!existsSync(runsDir))
+        return [];
+    const tag = `"kiln:${jobId}"`;
+    let names;
+    try {
+        names = readdirSync(runsDir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        const file = join(runsDir, name, "journal.jsonl");
+        if (!existsSync(file))
+            continue;
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!text.includes(tag))
+            continue;
+        found.push({ finished: /"t"\s*:\s*"run\.finished"/.test(text) });
+    }
+    return found;
+}
 function blockReason(config, now) {
     const events = readEvents(config.kilnDir, { warn: () => { } });
     if (pausedFrom(events))
@@ -591,8 +797,11 @@ function isTriggerEvent(event) {
 function triggerSummary(event) {
     if (event.event === "trigger.failed")
         return event.properties.error;
-    if (event.event === "trigger.skipped")
-        return event.properties.reason;
+    if (event.event === "trigger.skipped") {
+        return event.properties.external_id
+            ? `${event.properties.reason} ${event.properties.external_id}`
+            : event.properties.reason;
+    }
     if (event.event === "trigger.routed")
         return `${event.properties.action} ${event.properties.dedupe}`;
     if (event.event === "trigger.fired")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/kiln",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Run a workflow on any registered repo. A markdown spec is the input.",
   "license": "MIT",
   "type": "module",

package/prompts/kiln/review.md

@@ -1,6 +1,6 @@
 Kiln runs this review inside yak. The working directory is an isolated worktree at `{{input.baseRef}}`. That commit is the pull request head. Do not guess a branch name.
 
-Read the change. Return a draft review and nothing else. Do not post the review, approve the pull request, merge it, push, or comment. Do not change product code. Do not create, modify, or delete files. Read-only git and file inspection are allowed.
+Read the change. Return a draft review and nothing else. Do not post the review, approve the pull request, merge it, push, or comment. Kiln posts the draft only after a person approves the gate, and only as a comment. Do not change product code. Do not create, modify, or delete files. Read-only git and file inspection are allowed.
 
 Return JSON with `markdown` and `findings`. `findings` is a list. Each item has `severity` (`note`, `nit`, `warning`, or `blocking`), `file`, `line`, and `comment`. `comment` is the text a person might post later. `markdown` is the whole draft a person will read, and it must include every finding with its severity, file, line, and suggested comment. If you find nothing, return an empty `findings` list and say so in `markdown`.
 

package/workflows/review.yaml

@@ -1,9 +1,9 @@
 # Draft review of one pull request, run by yak (@lchase/yak).
 #
 # The agent returns findings (severity, file, line, suggested comment).
-# A person approves or rejects the draft in the Inbox. Approving does not
-# post, approve, or merge on GitHub: Kiln has no gated posting path for a
-# review comment, so the draft stops here.
+# A person approves or rejects the draft in the Inbox. Approving posts the
+# draft as a pull request comment. Kiln does not approve the pull request
+# or merge it. Rejecting or revising does not post.
 #
 # `reviewPrompt` in the kiln config replaces prompts/kiln/review.md.
 # The packaged file is the generic default.
@@ -60,5 +60,5 @@ steps:
             decision: { type: string, enum: [approve, reject] }
           required: [decision]
       render:
-        inline: "Draft review for \"{{input.title}}\"?\n\nApproving keeps this draft. Kiln does not post it to GitHub.\n\n{{draft.markdown}}"
+        inline: "Draft review for \"{{input.title}}\"?\n\nApproving posts this draft as a pull request comment. Kiln does not approve the pull request or merge it.\n\n{{draft.markdown}}"
     produces: approval