@lchase/kiln 0.0.0-stage → 0.3.0

package/dist/errors.js

@@ -0,0 +1,6 @@
+export class KilnConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KilnConfigError";
+    }
+}

package/dist/findings.js

@@ -0,0 +1,79 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { jobBasename } from "./paths.js";
+/**
+ * Workflow name for a spike, probe, or research job.
+ * An approved investigation is `done` with no pull request and no land.
+ */
+export const INVESTIGATION_WORKFLOW = "investigation";
+/**
+ * Headings the findings markdown must contain. The investigation prompt
+ * asks for these spellings. Kiln stores the agent's markdown only when
+ * every one of them is present.
+ */
+export const FINDINGS_HEADINGS = [
+    "## Questions",
+    "## Answers",
+    "## Unconfirmed",
+    "## Implications for dependent tickets",
+];
+/** `<kilnDir>/findings/<jobId>.md`. The job file does not store this path. */
+export function findingsFilePath(kilnDir, jobId) {
+    return join(kilnDir, "findings", `${jobBasename(jobId)}.md`);
+}
+/** Absolute path when the findings file is already on disk. */
+export function existingFindingsPath(kilnDir, jobId) {
+    const path = findingsFilePath(kilnDir, jobId);
+    return existsSync(path) ? path : undefined;
+}
+export function findingsMarkdownComplete(markdown) {
+    return FINDINGS_HEADINGS.every((heading) => markdown.includes(heading));
+}
+/**
+ * Store the approved findings document. Writing the same text again does
+ * not touch the file. A document missing a required heading is refused.
+ */
+export function writeFindings(kilnDir, jobId, markdown) {
+    if (!findingsMarkdownComplete(markdown)) {
+        throw new Error(`Findings for ${jobId} are missing a required section. Expected ${FINDINGS_HEADINGS.join(", ")}.`);
+    }
+    const path = findingsFilePath(kilnDir, jobId);
+    mkdirSync(dirname(path), { recursive: true });
+    const body = markdown.endsWith("\n") ? markdown : `${markdown}\n`;
+    if (existsSync(path) && readFileSync(path, "utf8") === body)
+        return path;
+    writeFileSync(path, body);
+    return path;
+}
+/** The explore step's `findings` artifact, when it is a complete markdown document. */
+export function readFindingsMarkdown(checkout, runId) {
+    const path = join(checkout, ".runs", runId, "artifacts", "findings.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || !("markdown" in parsed))
+            return undefined;
+        const markdown = parsed.markdown;
+        if (typeof markdown !== "string")
+            return undefined;
+        const text = markdown.trim();
+        if (!text || !findingsMarkdownComplete(text))
+            return undefined;
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Spec text handed to yak. Investigation dependencies contribute a
+ * `## Findings from <title>` section. The stored spec file is not modified.
+ */
+export function appendInvestigationFindings(specText, sections) {
+    if (sections.length === 0)
+        return specText;
+    const base = specText.endsWith("\n") ? specText : `${specText}\n`;
+    const blocks = sections.map((section) => `## Findings from ${section.title}\n\n${section.markdown.trim()}\n`);
+    return `${base}\n${blocks.join("\n")}`;
+}

package/dist/host.js

@@ -0,0 +1,223 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Git remote and GitHub CLI, behind one seam so tests can fake `gh` and point
+ * `origin` at a local bare repo. Nothing here merges a pull request or pushes
+ * the base branch.
+ */
+export class HostError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HostError";
+    }
+}
+export function defaultHost() {
+    return { github: realGitHub, git: realGitRemote };
+}
+const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: "0" });
+function gitResult(checkout, args) {
+    const result = spawnSync("git", args, { cwd: checkout, encoding: "utf8", env: gitEnv() });
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr || result.error?.message || "",
+    };
+}
+export const realGitRemote = {
+    fetch(checkout) {
+        const result = gitResult(checkout, ["fetch", "origin"]);
+        if (result.status !== 0) {
+            throw new HostError(`Could not fetch origin in ${checkout}: ${result.stderr.trim() || "git fetch failed"}`);
+        }
+    },
+    revParse(checkout, ref) {
+        const result = gitResult(checkout, ["rev-parse", "--verify", ref]);
+        const sha = result.stdout.trim();
+        if (result.status !== 0 || !/^[0-9a-f]{40}$/.test(sha)) {
+            throw new HostError(`Could not resolve ${ref} in ${checkout}: ${(result.stderr || result.stdout || "no such ref").trim()}`);
+        }
+        return sha;
+    },
+    remoteBranchSha(checkout, branch) {
+        const result = gitResult(checkout, ["ls-remote", "--heads", "origin", `refs/heads/${branch}`]);
+        if (result.status !== 0) {
+            throw new HostError(`Could not look up origin/${branch} in ${checkout}: ${result.stderr.trim() || "git ls-remote failed"}`);
+        }
+        const line = result.stdout
+            .split("\n")
+            .map((item) => item.trim())
+            .find((item) => item.endsWith(`refs/heads/${branch}`));
+        if (!line)
+            return null;
+        const sha = line.split(/\s+/)[0] ?? "";
+        return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+    },
+    pushBranch(checkout, branch, baseBranch) {
+        if (branch === baseBranch || branch === `refs/heads/${baseBranch}`) {
+            throw new HostError(`Refusing to push ${branch}: that is the base branch.`);
+        }
+        if (!/^yak\/[A-Za-z0-9._-]+$/.test(branch)) {
+            throw new HostError(`Refusing to push ${branch}: kiln only pushes yak/<run-id>.`);
+        }
+        const result = gitResult(checkout, [
+            "push",
+            "origin",
+            `refs/heads/${branch}:refs/heads/${branch}`,
+        ]);
+        if (result.status !== 0) {
+            throw new HostError(`Could not push ${branch}: ${result.stderr.trim() || "git push failed"}`);
+        }
+    },
+    defaultBranch(checkout) {
+        const symbolic = gitResult(checkout, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+        if (symbolic.status === 0) {
+            const name = symbolic.stdout.trim().replace(/^origin\//, "");
+            if (name && !name.includes(" "))
+                return name;
+        }
+        const listed = gitResult(checkout, ["ls-remote", "--symref", "origin", "HEAD"]);
+        if (listed.status === 0) {
+            const match = listed.stdout.match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD/m);
+            const name = match?.[1];
+            if (name)
+                return name;
+        }
+        throw new HostError(`Could not discover origin's default branch in ${checkout}. Pass --base when you register the repo.`);
+    },
+};
+function ghBin() {
+    return process.env.KILN_GH && process.env.KILN_GH.length > 0 ? process.env.KILN_GH : "gh";
+}
+function runGh(checkout, args) {
+    const bin = ghBin();
+    const result = spawnSync(bin, args, {
+        cwd: checkout,
+        encoding: "utf8",
+        env: { ...process.env, GH_PROMPT_DISABLED: "1", GIT_TERMINAL_PROMPT: "0" },
+    });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            throw new HostError(`gh is not installed (looked for ${bin}). Install the GitHub CLI from https://cli.github.com/ and run gh auth login, then run kiln tick again.`);
+        }
+        throw new HostError(`Could not run gh: ${result.error.message}`);
+    }
+    return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+function ghFailure(stderr, stdout) {
+    const detail = (stderr || stdout).trim() || "gh failed";
+    const auth = /auth|login|token|credential/i.test(detail);
+    const hint = auth
+        ? "Run gh auth login, then run kiln tick again."
+        : "Fix gh, then run kiln tick again.";
+    return new HostError(`Could not open a pull request: ${detail} ${hint}`);
+}
+function asState(value) {
+    if (value === "MERGED" || value === "CLOSED" || value === "OPEN")
+        return value;
+    return "OPEN";
+}
+function asMergedAt(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function toRef(raw, fallback) {
+    const number = typeof raw.number === "number" ? raw.number : Number.NaN;
+    const url = typeof raw.url === "string" ? raw.url : "";
+    if (!Number.isInteger(number) || number <= 0 || !url)
+        return null;
+    return {
+        number,
+        url,
+        state: asState(raw.state),
+        mergedAt: asMergedAt(raw.mergedAt),
+        head: typeof raw.headRefName === "string" && raw.headRefName.length > 0 ? raw.headRefName : fallback.head,
+        base: typeof raw.baseRefName === "string" && raw.baseRefName.length > 0 ? raw.baseRefName : fallback.base,
+    };
+}
+export const realGitHub = {
+    findByHead(checkout, branch) {
+        const result = runGh(checkout, [
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "all",
+            "--limit",
+            "30",
+            "--json",
+            "number,url,state,mergedAt,headRefName,baseRefName",
+        ]);
+        if (result.status !== 0)
+            throw ghFailure(result.stderr, result.stdout);
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout || "[]");
+        }
+        catch {
+            throw new HostError(`gh pr list returned data that is not JSON.`);
+        }
+        if (!Array.isArray(parsed))
+            throw new HostError(`gh pr list returned data that is not a list.`);
+        const matches = parsed
+            .map((item) => toRef(item, { head: branch, base: "" }))
+            .filter((item) => item !== null && item.head === branch);
+        const open = matches.find((item) => item.state === "OPEN");
+        if (open)
+            return open;
+        const merged = matches.find((item) => item.state === "MERGED" || item.mergedAt);
+        if (merged)
+            return merged;
+        return matches.sort((left, right) => right.number - left.number)[0] ?? null;
+    },
+    createDraft(input) {
+        const dir = mkdtempSync(join(tmpdir(), "kiln-pr-"));
+        const bodyFile = join(dir, "body.md");
+        writeFileSync(bodyFile, input.body);
+        try {
+            const result = runGh(input.checkout, [
+                "pr",
+                "create",
+                "--draft",
+                "--head",
+                input.head,
+                "--base",
+                input.base,
+                "--title",
+                input.title.replace(/[\r\n]+/g, " ").trim(),
+                "--body-file",
+                bodyFile,
+            ]);
+            if (result.status !== 0)
+                throw ghFailure(result.stderr, result.stdout);
+            const url = result.stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.startsWith("http"))
+                .at(-1);
+            const number = Number(url?.match(/\/pull\/(\d+)\s*$/)?.[1]);
+            if (!url || !Number.isInteger(number)) {
+                throw new HostError(`gh pr create did not return a pull request URL: ${result.stdout.trim()}`);
+            }
+            return { number, url, state: "OPEN", mergedAt: null, head: input.head, base: input.base };
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    },
+    view(checkout, number) {
+        const result = runGh(checkout, ["pr", "view", String(number), "--json", "state,mergedAt"]);
+        if (result.status !== 0)
+            throw ghFailure(result.stderr, result.stdout);
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch {
+            throw new HostError(`gh pr view returned data that is not JSON.`);
+        }
+        return { state: asState(parsed.state), mergedAt: asMergedAt(parsed.mergedAt) };
+    },
+};

package/dist/intake/file.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { titleFromSpec, writeJob } from "../jobs.js";
+/** `kiln add <workflow> --repo R --spec file.md` */
+export function addFromFile(config, input) {
+    const source = resolve(input.cwd, input.specPath);
+    let text;
+    try {
+        text = readFileSync(source, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read spec ${source}: ${message}`);
+    }
+    if (!text.trim()) {
+        throw new Error(`Spec ${source} is empty.`);
+    }
+    const title = input.title?.trim() || titleFromSpec(text, source);
+    return writeJob(config, {
+        workflow: input.workflow,
+        repo: input.repo,
+        specText: text,
+        title,
+        dependsOn: input.dependsOn,
+        ...(input.stack ? { stack: true } : {}),
+        source: { kind: "file", ref: source },
+        ...(input.now ? { now: input.now } : {}),
+    });
+}