@lchase/kiln 0.0.0-stage → 0.3.0

package/dist/reconcile.js

@@ -0,0 +1,141 @@
+import { INVESTIGATION_WORKFLOW } from "./findings.js";
+export function inFlightCount(observation) {
+    return observation.jobs.filter((job) => inFlight(job, observation)).length;
+}
+function inFlight(job, observation) {
+    if (job.error)
+        return false;
+    const state = jobState(job, observation);
+    return state === "running" || state === "needs-human" || state === "approved";
+}
+/**
+ * `deliver=local`: `done` is a finished run whose gate says approve.
+ * `deliver=pr`: that landed run is `in-review` while the pull request is open
+ * (and in the gap before tick opens it) and `done` only once it has merged.
+ * `approved` is the approve decision while the run is still alive. It holds
+ * a slot and does not unblock dependents. An ok run with no readable
+ * decision is `failed`, so a missing artifact cannot unblock the next job.
+ * An investigation is `done` on approve and never `in-review`.
+ */
+export function jobState(job, observation) {
+    if (job.launchFailed && !job.run)
+        return "failed";
+    if (job.run) {
+        if (isLanded(job))
+            return landedState(job);
+        if (job.run.status === "ok" && job.run.gateDecision === "reject")
+            return "rejected";
+        if (job.run.status === "ok")
+            return "failed";
+        if (job.run.status === "failed")
+            return "failed";
+        if (job.run.status === "dead")
+            return "dead";
+        if (job.run.status === "suspended")
+            return "needs-human";
+        if (job.run.gateDecision === "approve")
+            return "approved";
+        return "running";
+    }
+    if (job.launching)
+        return "running";
+    if (!dependenciesMet(job, observation))
+        return "blocked";
+    if (job.launchError)
+        return "failed";
+    return "queued";
+}
+/**
+ * After-merged (the default) needs every upstream `done`.
+ * Stacked needs its one upstream landed (approved and the run finished ok),
+ * which is true for `in-review` as well as `done`.
+ */
+export function dependenciesMet(job, observation) {
+    return job.dependsOn.every((dep) => {
+        const upstream = observation.jobs.find((candidate) => candidate.jobId === dep);
+        if (!upstream)
+            return false;
+        return job.stack ? isLanded(upstream) : isDone(upstream);
+    });
+}
+/** Run finished ok and the gate says approve. The branch `yak/<run-id>` has landed. */
+export function isLanded(job) {
+    return job.run?.status === "ok" && job.run.gateDecision === "approve";
+}
+/**
+ * `deliver=local`: landed. `deliver=pr`: landed and the pull request has merged.
+ * An investigation is done once the gate says approve. There is no pull request.
+ */
+export function isDone(job) {
+    if (!isLanded(job))
+        return false;
+    if (job.workflow === INVESTIGATION_WORKFLOW)
+        return true;
+    if ((job.deliver ?? "local") !== "pr")
+        return true;
+    return job.delivery?.merged === true || job.delivery?.prState === "MERGED";
+}
+function landedState(job) {
+    if (job.workflow === INVESTIGATION_WORKFLOW)
+        return "done";
+    if ((job.deliver ?? "local") !== "pr")
+        return "done";
+    const delivery = job.delivery;
+    if (delivery?.merged || delivery?.prState === "MERGED")
+        return "done";
+    if (delivery?.prState === "CLOSED")
+        return "failed";
+    if (delivery?.prNumber)
+        return "in-review";
+    if (delivery?.error)
+        return "failed";
+    return "in-review";
+}
+function needsDelivery(job) {
+    if (job.error)
+        return false;
+    if (job.workflow === INVESTIGATION_WORKFLOW)
+        return false;
+    if ((job.deliver ?? "local") !== "pr")
+        return false;
+    if (!isLanded(job))
+        return false;
+    if (job.delivery?.merged || job.delivery?.prState === "MERGED")
+        return false;
+    if (job.delivery?.prState === "CLOSED")
+        return false;
+    if (job.delivery?.prNumber)
+        return false;
+    return true;
+}
+function canLaunch(job, observation) {
+    if (job.error || job.run || job.launching || job.launchFailed)
+        return false;
+    return dependenciesMet(job, observation);
+}
+export function decide(observation) {
+    const actions = observation.breadcrumbsToClear.map((crumb) => ({
+        type: "clear-breadcrumb",
+        path: crumb.path,
+    }));
+    for (const job of observation.jobs) {
+        if (job.error || job.workflow !== INVESTIGATION_WORKFLOW)
+            continue;
+        if (!isLanded(job) || job.findingsPath)
+            continue;
+        actions.push({ type: "record-findings", jobId: job.jobId });
+    }
+    for (const job of observation.jobs) {
+        if (!needsDelivery(job))
+            continue;
+        actions.push({ type: "deliver", jobId: job.jobId, repo: job.repo });
+    }
+    if (inFlightCount(observation) >= observation.maxConcurrent)
+        return actions;
+    const ready = observation.jobs.filter((job) => canLaunch(job, observation));
+    const healthy = ready.filter((job) => !job.launchError);
+    const picked = healthy[0] ?? ready[0];
+    if (picked)
+        actions.push({ type: "launch", jobId: picked.jobId, repo: picked.repo });
+    return actions;
+}

package/dist/report.js

@@ -0,0 +1,254 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { INVESTIGATION_WORKFLOW } from "./findings.js";
+import { inFlightCount, isDone, isLanded, jobState, } from "./reconcile.js";
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Absolute path of the yak CLI, from the installed package's `bin.yak`. */
+export function yakCliPath() {
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve("@lchase/yak/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const relative = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.yak;
+    if (!relative) {
+        throw new Error(`${pkgPath} has no "yak" bin.`);
+    }
+    return join(dirname(pkgPath), relative);
+}
+export function yakInvocation(subcommand, runId) {
+    return `${shellQuote(process.execPath)} ${shellQuote(yakCliPath())} ${subcommand} ${shellQuote(runId)}`;
+}
+/** One variant of the command that answers an open gate and continues the run. */
+export function gateAnswerCommand(checkout, runId, gate, choice, title) {
+    const pendingDir = shellQuote(`.runs/${runId}/pending`);
+    const answerFile = shellQuote(`.runs/${runId}/pending/${gate.stepId}.answer.json`);
+    const field = gate.answerField ?? "decision";
+    const answer = JSON.stringify({ [field]: choice });
+    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)}`;
+}
+/**
+ * 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}.`);
+    }
+    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 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.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);
+        }
+    }
+    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;
+}
+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 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,
+            invalidReason: job.error,
+            prPending: false,
+            prClosedUnmerged: false,
+            noReadableApproval: false,
+            gates: [],
+            canApprove: false,
+            canReject: false,
+        };
+    }
+    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;
+    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,
+        ...(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,
+        ...(state === "dead" && job.run
+            ? { 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")),
+    };
+}
+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) {
+            reasons.push({ dep, detail: `blocked on missing job ${dep}` });
+            continue;
+        }
+        if (job.stack) {
+            if (!isLanded(upstream))
+                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") {
+            reasons.push({ dep, detail: `waiting for PR #${number} to merge` });
+            continue;
+        }
+        if ((upstream.deliver ?? "local") === "pr" && isLanded(upstream)) {
+            reasons.push({ dep, detail: `waiting for ${dep} to open a pull request` });
+        }
+    }
+    return reasons;
+}
+export function renderTick(observation, actions, launches, delivers = [], findings = []) {
+    const lines = [`tick  inFlight=${inFlightCount(observation)}  maxConcurrent=${observation.maxConcurrent}`];
+    for (const job of observation.jobs) {
+        if (job.error)
+            lines.push(`skip ${job.jobId} (invalid: ${job.error})`);
+    }
+    for (const action of actions) {
+        if (action.type === "clear-breadcrumb")
+            lines.push(`clear breadcrumb ${action.path}`);
+    }
+    for (const deliver of delivers) {
+        lines.push(deliver.ok
+            ? `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 launch of launches) {
+        lines.push(`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") &&
+        launches.length === 0 &&
+        delivers.length === 0 &&
+        findings.length === 0) {
+        lines.push("nothing to launch");
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/schemas.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+/**
+ * Kiln config file. `repos` is an open map: any name, not a fixed set.
+ * `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`).
+ */
+/**
+ * `deliver` defaults to `local` when omitted: land on `yak/<run-id>` and do not push.
+ * `pr` pushes that branch and opens a draft pull request against `base`.
+ * `base` defaults to origin's default branch, discovered with git, when omitted.
+ */
+export const RepoEntrySchema = z.object({
+    path: z.string().min(1),
+    test: z.string().min(1).optional(),
+    deliver: z.enum(["local", "pr"]).optional(),
+    base: z.string().min(1).optional(),
+});
+/**
+ * Optional Jira Cloud credentials in the gitignored kiln config.
+ * `JIRA_BASE_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` override these.
+ * Empty strings are treated as unset. The token is never copied into a job.
+ */
+export const JiraConfigSchema = z.object({
+    baseUrl: z.string().optional(),
+    email: z.string().optional(),
+    apiToken: z.string().optional(),
+});
+export const KilnConfigFileSchema = z.object({
+    note: z.string().min(1).optional(),
+    maxConcurrent: z.number().int().min(1).optional(),
+    adapter: z.enum(["mock", "claude-code"]).optional(),
+    repos: z.record(z.string(), RepoEntrySchema),
+    jira: JiraConfigSchema.optional(),
+});
+/**
+ * Where a job came from. Adapters set this; tick and reconcile do not branch on it.
+ * `ref` is an absolute spec path (`file`), `inline` or `stdin` (`prompt`), the
+ * absolute ticket path (`tickets`), or the issue key (`jira`, such as `PROJ-123`).
+ */
+export const JobSourceSchema = z.object({
+    kind: z.enum(["file", "prompt", "tickets", "jira"]),
+    ref: z.string().min(1),
+});
+/**
+ * One unit of factory work. Stored as `<kilnDir>/jobs/<id>.json`.
+ * `spec` is a markdown file under the kiln directory.
+ * `dependsOn` names other job ids. There is no plan and no stored state.
+ * Every intake writes this same shape. `source` is omitted on jobs written
+ * before intake; those files still parse.
+ */
+export const JobSchema = z.object({
+    id: z.string().min(1),
+    repo: z.string().min(1),
+    workflow: z.string().min(1),
+    spec: z.string().min(1),
+    title: z.string().min(1),
+    dependsOn: z.array(z.string().min(1)).optional(),
+    /**
+     * 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(),
+    createdAt: z.string().min(1),
+});
+/**
+ * Derived from the yak journal, gate files, and (for `deliver=pr`) the
+ * delivery record plus `gh pr view`. Never written into the job file.
+ *
+ * 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. 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`.
+ */
+export const JOB_STATES = [
+    "queued",
+    "blocked",
+    "running",
+    "needs-human",
+    "approved",
+    "rejected",
+    "failed",
+    "dead",
+    "in-review",
+    "done",
+];