@lchase/kiln 0.3.0 → 0.4.0

package/dist/board.js

@@ -0,0 +1,326 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { scheduledRetry } from "./attention.js";
+const FEATURE_STAGES = ["spec", "build", "review", "approve", "land", "pr-review"];
+const CATALOG = [
+    { id: "queued", label: "Queued", who: "waiting · deps", tone: "queued" },
+    { id: "spec", label: "Spec", who: "spec-writer · opus" },
+    { id: "build", label: "Build", who: "builder · opus" },
+    { id: "review", label: "Review", who: "sec · ux · ui · code" },
+    { id: "approve", label: "Approve", who: "approver · opus" },
+    { id: "explore", label: "Explore", who: "investigator · opus" },
+    { id: "land", label: "Land", who: "git commit" },
+    { id: "pr-review", label: "PR review", who: "pr-sync" },
+    { id: "merged", label: "Merged", who: "main", tone: "merged" },
+    { id: "needs-human", label: "Needs human", who: "approve · retry", tone: "human" },
+];
+const STEP_STAGE = {
+    spec: "spec",
+    build: "build",
+    verify: "build",
+    security: "review",
+    ux: "review",
+    ui: "review",
+    code: "review",
+    approver: "approve",
+    approve: "needs-human",
+    land: "land",
+    explore: "explore",
+};
+const HUMAN_STATES = new Set(["needs-human", "failed", "dead", "invalid", "rejected"]);
+/**
+ * Column for one job. Human gates and broken runs sit in Needs human.
+ * A failed job with an automatic retry still scheduled stays on the step
+ * its last run reached. `scheduledRetry` is that decision.
+ */
+export function stageOf(job) {
+    if (scheduledRetry(job))
+        return runStage(job);
+    if (HUMAN_STATES.has(job.state))
+        return "needs-human";
+    if (job.state === "in-review")
+        return "pr-review";
+    if (job.state === "done")
+        return "merged";
+    const current = job.steps.find((step) => step.phase === "current" || step.phase === "failed");
+    if (job.state === "queued" || job.state === "blocked")
+        return "queued";
+    if (job.state === "approved") {
+        if (current && current.id !== "land" && current.id !== "approve" && STEP_STAGE[current.id])
+            return STEP_STAGE[current.id];
+        return "land";
+    }
+    if (current && STEP_STAGE[current.id])
+        return STEP_STAGE[current.id];
+    return runStage(job);
+}
+/**
+ * Stage of the last step the run actually reached.
+ * The approve gate's column is Needs human; a scheduled retry is not a gate,
+ * so that step stays on Approve. Spec or Explore when the run never started a step.
+ */
+function runStage(job) {
+    const last = [...job.steps].reverse().find((step) => step.phase === "current" || step.phase === "failed");
+    const stage = last ? STEP_STAGE[last.id] : undefined;
+    if (stage && stage !== "needs-human")
+        return stage;
+    if (stage === "needs-human") {
+        const earlier = [...job.steps].reverse().find((step) => {
+            const mapped = STEP_STAGE[step.id];
+            return step.phase === "done" && mapped !== undefined && mapped !== "needs-human";
+        });
+        if (earlier)
+            return STEP_STAGE[earlier.id] ?? "approve";
+        return "approve";
+    }
+    return job.workflow === "investigation" ? "explore" : "spec";
+}
+/** Stages to render. An empty kiln still shows the feature pipeline, collapsed. */
+export function stagesFor(jobs) {
+    const workflows = new Set(jobs.map((job) => job.workflow));
+    const wanted = new Set();
+    if (jobs.length === 0 || workflows.has("feature") || [...workflows].some((name) => name !== "investigation")) {
+        for (const id of FEATURE_STAGES)
+            wanted.add(id);
+    }
+    if (workflows.has("investigation"))
+        wanted.add("explore");
+    wanted.add("queued");
+    wanted.add("merged");
+    wanted.add("needs-human");
+    for (const job of jobs)
+        wanted.add(stageOf(job));
+    return CATALOG.filter((stage) => wanted.has(stage.id));
+}
+const REVIEW_FILE = /^(security|ux|ui|code)(?:\.(\d+))?\.json$/;
+const TEXT_LIMIT = 8_000;
+export function readReviewRounds(runDir) {
+    if (!runDir)
+        return [];
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const rounds = new Map();
+    for (const name of names) {
+        const match = REVIEW_FILE.exec(name);
+        if (!match?.[1])
+            continue;
+        const n = match[2] ? Number(match[2]) : 1;
+        const round = rounds.get(n) ?? { n };
+        const verdict = verdictOf(readJson(join(dir, name)));
+        if (verdict) {
+            if (match[1] === "security")
+                round.security = verdict;
+            else if (match[1] === "ux")
+                round.ux = verdict;
+            else if (match[1] === "ui")
+                round.ui = verdict;
+            else if (match[1] === "code")
+                round.code = verdict;
+        }
+        rounds.set(n, round);
+    }
+    return [...rounds.values()].sort((left, right) => left.n - right.n);
+}
+export function readBoardFiles(input) {
+    const files = [];
+    const spec = readText(input.specPath);
+    if (spec)
+        files.push({ id: "spec", group: "Job", label: "spec.md", text: spec });
+    const build = latestArtifact(input.runDir, "build");
+    if (build) {
+        const doc = artifactDoc(build);
+        files.push({ id: "build", group: "Job", label: "build.md", text: doc.text, ...(doc.tone ? { tone: doc.tone } : {}) });
+    }
+    else if (input.diffSummary?.trim()) {
+        files.push({ id: "build", group: "Job", label: "build.md", text: input.diffSummary.trim() });
+    }
+    const decision = latestArtifact(input.runDir, "decision");
+    if (decision) {
+        const doc = artifactDoc(decision);
+        files.push({ id: "decision", group: "Job", label: "decision.md", text: doc.text, ...(doc.tone ? { tone: doc.tone } : {}) });
+    }
+    const findingsFile = readText(input.findingsPath);
+    const findingsArtifact = latestArtifact(input.runDir, "findings");
+    const findingsMarkdown = findingsFile
+        || (isRecord(findingsArtifact) && typeof findingsArtifact.markdown === "string" ? findingsArtifact.markdown : "");
+    if (input.workflow === "investigation" && findingsMarkdown.trim()) {
+        files.push({ id: "findings", group: "Job", label: "findings.md", text: clip(findingsMarkdown) });
+    }
+    for (const gate of input.gates ?? []) {
+        const body = gate.rendered?.trim() || gate.prompt?.trim();
+        if (body) {
+            const label = input.workflow === "investigation" ? "findings.md" : "gate.md";
+            if (!files.some((file) => file.label === label && file.text.includes(body.slice(0, 40)))) {
+                files.push({ id: `gate-${gate.stepId}`, group: "Job", label, text: clip(body) });
+            }
+        }
+        for (const artifact of gate.artifacts ?? []) {
+            if (!artifact.summary?.trim())
+                continue;
+            const label = artifact.name.endsWith(".md") ? artifact.name : `${artifact.name}.md`;
+            if (files.some((file) => file.label === label || file.label === artifact.name))
+                continue;
+            const tone = toneFromSummary(artifact.summary);
+            files.push({
+                id: `artifact-${gate.stepId}-${artifact.name}`,
+                group: "Job",
+                label,
+                text: clip(artifact.summary),
+                ...(tone ? { tone } : {}),
+            });
+        }
+    }
+    if (input.runDir)
+        addReviewFiles(files, input.runDir);
+    addGateReviews(files, input.gates ?? []);
+    if (input.logTail?.trim()) {
+        files.push({ id: "log", group: "Job", label: "log", text: clip(input.logTail) });
+    }
+    return files;
+}
+function addReviewFiles(files, runDir) {
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const rows = [];
+    for (const name of names) {
+        const match = REVIEW_FILE.exec(name);
+        if (!match?.[1])
+            continue;
+        rows.push({ n: match[2] ? Number(match[2]) : 1, kind: match[1], file: name });
+    }
+    const order = ["security", "ux", "ui", "code"];
+    rows.sort((left, right) => left.n - right.n || order.indexOf(left.kind) - order.indexOf(right.kind));
+    for (const row of rows) {
+        const doc = artifactDoc(readJson(join(dir, row.file)));
+        files.push({
+            id: `r${row.n}-${row.kind}`,
+            group: `Round ${row.n}`,
+            label: row.kind,
+            text: doc.text,
+            ...(doc.tone ? { tone: doc.tone } : {}),
+        });
+    }
+}
+function latestArtifact(runDir, name) {
+    if (!runDir)
+        return undefined;
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return undefined;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return undefined;
+    }
+    let best;
+    const pattern = new RegExp(`^${name}(?:\\.(\\d+))?\\.json$`);
+    for (const file of names) {
+        const match = pattern.exec(file);
+        if (!match)
+            continue;
+        const iter = match[1] ? Number(match[1]) : 0;
+        if (!best || iter >= best.iter)
+            best = { iter, file };
+    }
+    return best ? readJson(join(dir, best.file)) : undefined;
+}
+function artifactDoc(value) {
+    if (!isRecord(value))
+        return { text: clip(typeof value === "string" ? value : "") };
+    const head = typeof value.verdict === "string" ? value.verdict : typeof value.decision === "string" ? value.decision : typeof value.status === "string" ? value.status : "";
+    const body = typeof value.findings === "string"
+        ? value.findings
+        : typeof value.reason === "string"
+            ? value.reason
+            : typeof value.summary === "string"
+                ? value.summary
+                : typeof value.markdown === "string"
+                    ? value.markdown
+                    : JSON.stringify(value, null, 2);
+    const tone = toneOf(head);
+    const text = head ? `VERDICT: ${head}\n\n${body}` : body;
+    return { text: clip(text), ...(tone ? { tone } : {}) };
+}
+function toneOf(head) {
+    if (head === "PASS" || head === "APPROVE" || head === "READY")
+        return "good";
+    if (head === "CHANGES")
+        return "warn";
+    if (head === "ESCALATE" || head === "BLOCKED")
+        return "stop";
+    return undefined;
+}
+function toneFromSummary(summary) {
+    const head = summary.trim().split(/[\s—-]/)[0] ?? "";
+    return toneOf(head);
+}
+function addGateReviews(files, gates) {
+    const known = new Set(files.filter((file) => file.group.startsWith("Round")).map((file) => file.label));
+    for (const gate of gates) {
+        for (const review of gate.reviews ?? []) {
+            if (!review.summary?.trim() || known.has(review.name))
+                continue;
+            known.add(review.name);
+            const tone = toneFromSummary(review.summary);
+            files.push({
+                id: `review-${review.name}`,
+                group: "Round 1",
+                label: review.name,
+                text: clip(review.summary),
+                ...(tone ? { tone } : {}),
+            });
+        }
+    }
+}
+function verdictOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    const verdict = value.verdict;
+    return typeof verdict === "string" && verdict.trim() ? verdict.trim() : undefined;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readText(file) {
+    if (!file || !existsSync(file))
+        return undefined;
+    try {
+        const text = readFileSync(file, "utf8").trim();
+        return text ? clip(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function clip(text) {
+    const trimmed = text.trim();
+    if (trimmed.length <= TEXT_LIMIT)
+        return trimmed;
+    return `${trimmed.slice(0, TEXT_LIMIT - 1)}…`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { addRepo, renderRepoList, resolveKilnConfig } from "./config.js";
-import { answerJob, runStatus, runTick } from "./driver.js";
+import { answerJob, retryJob, runStatus, runTick } from "./driver.js";
 import { startServe } from "./serve.js";
 import { addFromFile } from "./intake/file.js";
 import { addFromJira } from "./intake/jira.js";
@@ -17,6 +17,7 @@ function usage() {
         "       kiln status [jobId] [--config <file>]",
         "       kiln approve <jobId> [--config <file>]",
         "       kiln reject <jobId> [--config <file>]",
+        "       kiln retry <jobId> [--config <file>]",
         "       kiln serve [--port 4100] [--tick <seconds>|--no-tick] [--config <file>]",
         "",
         "repo add registers a checkout. A relative path is stored absolute, resolved",
@@ -49,12 +50,21 @@ function usage() {
         "yak/<run-id> and opens a draft pull request. An investigation is done when",
         "its gate is approved. It does not open a pull request. status prints the",
         "derived state, and the findings path once an investigation is approved.",
-        "approve and reject answer the human gate.",
+        "approve and reject answer the human gate. retry launches a failed or dead",
+        "job again, the same way tick launches, and clears the attempt ledger.",
+        "A landed job that only failed to open its pull request is delivered again.",
+        "A running job with no yak event or log output for stallTimeoutMs (default",
+        "15 minutes; 0 disables it) is killed and retried. A crash, a non-zero exit,",
+        "or a process that is already gone when tick or serve starts (orphaned) retries",
+        "after 10s, 20s, 40s, and so on, capped at 5 minutes, up to maxAttempts",
+        "(default 3). The job is then dead. A rejected gate is not retried.",
+        "Attempts are files under the kiln home, not fields on the job.",
         "",
-        "serve listens on 127.0.0.1. The inbox lists needs-human jobs. The board",
-        "groups every job by the same derived state as status. Approve and reject",
-        "call the same functions as the CLI. POST from another origin is rejected.",
-        "A tick runs every 30 seconds unless --no-tick is set, using the tick lock.",
+        "serve listens on 127.0.0.1. The page is a board of workflow stages:",
+        "queued, spec, build, review, approve, land, PR review, merged, and needs human.",
+        "Empty stages collapse. Approve, reject, and retry call the same",
+        "functions as the CLI. POST from another origin is rejected. A tick",
+        "runs every 30 seconds unless --no-tick is set, using the tick lock.",
     ].join("\n"));
     process.exit(2);
 }
@@ -319,6 +329,16 @@ function statusCommand(argv) {
     const config = resolveKilnConfig({ configPath: flags.configPath });
     process.stdout.write(runStatus(config, flags.positionals[0]));
 }
+function retryCommand(argv) {
+    const flags = parseFlags(argv);
+    rejectServeFlags(flags);
+    const jobId = flags.positionals[0];
+    if (!jobId || flags.positionals.length !== 1 || flags.test || hasIntakeFlags(flags) || flags.deliver || flags.base || flags.stack) {
+        usage();
+    }
+    const config = resolveKilnConfig({ configPath: flags.configPath });
+    process.stdout.write(retryJob(config, jobId));
+}
 function gateCommand(choice, argv) {
     const flags = parseFlags(argv);
     rejectServeFlags(flags);
@@ -394,6 +414,10 @@ async function main() {
         gateCommand("reject", argv.slice(1));
         return;
     }
+    if (command === "retry") {
+        retryCommand(argv.slice(1));
+        return;
+    }
     if (command === "serve") {
         await serveCommand(argv.slice(1));
         return;

package/dist/config.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { KilnConfigError } from "./errors.js";
-import { KilnConfigFileSchema } from "./schemas.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, } from "./schemas.js";
 const CONFIG_NAME = "kiln.config.json";
 const REPO_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function loadKilnConfig(configPath, options = {}) {
@@ -45,6 +45,8 @@ export function loadKilnConfig(configPath, options = {}) {
         kilnDir,
         jobsDir: join(kilnDir, "jobs"),
         maxConcurrent: parsed.data.maxConcurrent ?? 2,
+        stallTimeoutMs: parsed.data.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS,
+        maxAttempts: parsed.data.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
         adapter: parsed.data.adapter ?? "claude-code",
         ...(jira ? { jira } : {}),
     };