@lchase/kiln 0.1.0 → 0.3.0

package/dist/serve.js

@@ -0,0 +1,351 @@
+import { createServer } from "node:http";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { answerJob, readStatus, runTick } from "./driver.js";
+import { INVESTIGATION_WORKFLOW } from "./findings.js";
+import { packageRoot } from "./paths.js";
+import { renderBoard, renderInbox, renderMessagePage, renderTextPage } from "./serve-page.js";
+const BODY_LIMIT = 65_536;
+const TEXT_LIMIT = 100_000;
+const JOB_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Local UI over the same derived job view as `kiln status`.
+ * Listens on 127.0.0.1 only. Resolves when the process is signalled.
+ */
+export function startServe(options) {
+    const css = loadServeCss();
+    const secrets = secretValues(options.config);
+    let port = options.port;
+    return new Promise((resolvePromise, reject) => {
+        const server = createServer((req, res) => {
+            void handle(req, res, options.config, () => port, css, secrets).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                const status = statusCode(error) ?? 500;
+                sendJson(res, status, { error: redact(message, secrets) }, secrets);
+            });
+        });
+        server.on("error", reject);
+        let stopped = false;
+        let timer;
+        let firstTick;
+        const shutdown = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            if (firstTick)
+                clearTimeout(firstTick);
+            server.close(() => resolvePromise());
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+        server.listen(options.port, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("kiln serve did not bind a TCP port."));
+                return;
+            }
+            port = address.port;
+            process.stdout.write(`listening http://${address.address}:${address.port}\n`);
+            if (options.tickSeconds === undefined)
+                return;
+            const tick = () => {
+                if (stopped)
+                    return;
+                safeTick(options.config, secrets);
+            };
+            firstTick = setTimeout(tick, 0);
+            timer = setInterval(tick, options.tickSeconds * 1000);
+        });
+    });
+}
+export function loadServeCss() {
+    const path = join(packageRoot(), "assets", "serve.css");
+    if (!existsSync(path)) {
+        throw new Error(`Kiln serve stylesheet is missing at ${path}.`);
+    }
+    return readFileSync(path, "utf8");
+}
+function safeTick(config, secrets) {
+    try {
+        runTick(config);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`tick: ${redact(message, secrets)}\n`);
+    }
+}
+async function handle(req, res, config, boundPort, css, secrets) {
+    const method = req.method ?? "GET";
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    const path = url.pathname;
+    if (method === "GET" && path === "/favicon.ico") {
+        res.writeHead(204, { Connection: "close", "Cache-Control": "no-store" });
+        res.end();
+        return;
+    }
+    if (method === "POST") {
+        await drain(req);
+        if (!originAllowed(req, boundPort())) {
+            sendJson(res, 403, { error: "Cross-origin request rejected." }, secrets);
+            return;
+        }
+        const action = /^\/api\/jobs\/([^/]+)\/(approve|reject)$/.exec(path);
+        if (!action?.[1] || (action[2] !== "approve" && action[2] !== "reject")) {
+            sendJson(res, 404, { error: "Not found." }, secrets);
+            return;
+        }
+        const jobId = parseJobId(action[1]);
+        if (!jobId) {
+            sendJson(res, 404, { error: "Not found." }, secrets);
+            return;
+        }
+        await answer(req, res, config, css, secrets, jobId, action[2]);
+        return;
+    }
+    if (method !== "GET" && method !== "HEAD") {
+        sendJson(res, 405, { error: "Method not allowed." }, secrets);
+        return;
+    }
+    if (path === "/" || path === "") {
+        sendHtml(res, 200, renderInbox(css, readStatus(config)), secrets);
+        return;
+    }
+    if (path === "/board") {
+        sendHtml(res, 200, renderBoard(css, readStatus(config)), secrets);
+        return;
+    }
+    if (path === "/api/jobs") {
+        sendJson(res, 200, readStatus(config), secrets);
+        return;
+    }
+    const apiJob = /^\/api\/jobs\/([^/]+)$/.exec(path);
+    if (apiJob?.[1]) {
+        const jobId = parseJobId(apiJob[1]);
+        const job = jobId ? findJob(config, jobId) : undefined;
+        if (!job) {
+            sendJson(res, 404, { error: jobId ? `No job ${jobId}.` : "Not found." }, secrets);
+            return;
+        }
+        sendJson(res, 200, job, secrets);
+        return;
+    }
+    const page = /^\/jobs\/([^/]+)\/(spec|log|findings)$/.exec(path);
+    if (page?.[1] && (page[2] === "spec" || page[2] === "log" || page[2] === "findings")) {
+        const jobId = parseJobId(page[1]);
+        const job = jobId ? findJob(config, jobId) : undefined;
+        if (!job) {
+            sendHtml(res, 404, renderMessagePage(css, "Not found", jobId ? `No job ${jobId}.` : "Not found."), secrets);
+            return;
+        }
+        if (page[2] === "findings") {
+            sendFindings(res, config, css, secrets, job);
+            return;
+        }
+        const target = page[2] === "spec" ? job.specPath : job.logPath;
+        if (!target) {
+            sendHtml(res, 404, renderMessagePage(css, "Not found", page[2] === "log" ? "No log yet." : "No spec."), secrets);
+            return;
+        }
+        const text = readInside(config.kilnDir, target);
+        if (text === undefined) {
+            sendHtml(res, 404, renderMessagePage(css, "Not found", "That file is not in the kiln directory."), secrets);
+            return;
+        }
+        const title = page[2] === "spec" ? `${job.title} spec` : `${job.title} log`;
+        sendHtml(res, 200, renderTextPage(css, title, text), secrets);
+        return;
+    }
+    if (path.startsWith("/api/"))
+        sendJson(res, 404, { error: "Not found." }, secrets);
+    else
+        sendHtml(res, 404, renderMessagePage(css, "Not found", "Not found."), secrets);
+}
+async function answer(req, res, config, css, secrets, jobId, choice) {
+    try {
+        answerJob(config, jobId, choice);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const status = message.startsWith("No job ") ? 404 : 409;
+        if (wantsJson(req))
+            sendJson(res, status, { error: message }, secrets);
+        else
+            sendHtml(res, status, renderMessagePage(css, "Could not answer", message), secrets);
+        return;
+    }
+    const job = findJob(config, jobId);
+    if (wantsJson(req)) {
+        sendJson(res, 200, { ok: true, job }, secrets);
+        return;
+    }
+    redirect(res, redirectTarget(req));
+}
+function sendFindings(res, config, css, secrets, job) {
+    if (job.workflow !== INVESTIGATION_WORKFLOW) {
+        sendHtml(res, 404, renderMessagePage(css, "Not found", "Not found."), secrets);
+        return;
+    }
+    if (!job.findingsPath) {
+        sendHtml(res, 404, renderMessagePage(css, "Not found", "No findings yet."), secrets);
+        return;
+    }
+    const text = readInside(config.kilnDir, job.findingsPath);
+    if (text === undefined) {
+        sendHtml(res, 404, renderMessagePage(css, "Not found", "That file is not in the kiln directory."), secrets);
+        return;
+    }
+    sendHtml(res, 200, renderTextPage(css, `${job.title} findings`, text), secrets);
+}
+function findJob(config, jobId) {
+    try {
+        return readStatus(config, jobId).jobs[0];
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === `No job ${jobId}.`)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Browsers send Origin on POST. A cross-site page cannot use this server:
+ * the header has to be exactly `http://127.0.0.1:<bound port>`.
+ * Curl and other non-browser clients omit Origin and are allowed.
+ * `Sec-Fetch-Site: cross-site` is rejected even when Origin is absent.
+ */
+export function originAllowed(req, port) {
+    const fetchSite = req.headers["sec-fetch-site"];
+    if (fetchSite === "cross-site")
+        return false;
+    const origin = req.headers.origin;
+    if (Array.isArray(origin))
+        return false;
+    if (origin === undefined)
+        return true;
+    return origin === `http://127.0.0.1:${port}`;
+}
+function redirectTarget(req) {
+    const referer = req.headers.referer;
+    if (typeof referer !== "string")
+        return "/";
+    try {
+        const url = new URL(referer);
+        if (url.pathname === "/board")
+            return "/board";
+    }
+    catch {
+        return "/";
+    }
+    return "/";
+}
+function wantsJson(req) {
+    const accept = headerValue(req.headers.accept);
+    if (accept.includes("application/json"))
+        return true;
+    return headerValue(req.headers["content-type"]).includes("application/json");
+}
+function headerValue(value) {
+    if (Array.isArray(value))
+        return value.join(",");
+    return value ?? "";
+}
+function parseJobId(raw) {
+    let id;
+    try {
+        id = decodeURIComponent(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!JOB_ID.test(id))
+        return undefined;
+    return id;
+}
+function readInside(kilnDir, target) {
+    let root;
+    try {
+        root = realpathSync(resolve(kilnDir));
+    }
+    catch {
+        return undefined;
+    }
+    const resolved = resolve(target);
+    if (resolved !== root && !resolved.startsWith(root + sep))
+        return undefined;
+    let real;
+    try {
+        real = realpathSync(resolved);
+    }
+    catch {
+        return undefined;
+    }
+    if (real !== root && !real.startsWith(root + sep))
+        return undefined;
+    const text = readFileSync(real, "utf8");
+    if (text.length <= TEXT_LIMIT)
+        return text;
+    return `showing the last ${TEXT_LIMIT} characters\n\n${text.slice(text.length - TEXT_LIMIT)}`;
+}
+async function drain(req) {
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > BODY_LIMIT) {
+            const error = new Error("Request body is too large.");
+            error.statusCode = 413;
+            throw error;
+        }
+    }
+}
+function statusCode(error) {
+    if (typeof error === "object" && error !== null && "statusCode" in error) {
+        const code = error.statusCode;
+        if (typeof code === "number")
+            return code;
+    }
+    return undefined;
+}
+function sendHtml(res, status, html, secrets) {
+    const body = redact(html, secrets);
+    res.writeHead(status, {
+        "Content-Type": "text/html; charset=utf-8",
+        Connection: "close",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+        "Referrer-Policy": "same-origin",
+    });
+    res.end(body);
+}
+function sendJson(res, status, value, secrets) {
+    const body = redact(`${JSON.stringify(value, null, 2)}\n`, secrets);
+    res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        Connection: "close",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+    });
+    res.end(body);
+}
+function redirect(res, location) {
+    res.writeHead(303, { Location: location, Connection: "close", "Cache-Control": "no-store" });
+    res.end();
+}
+function secretValues(config) {
+    const values = [config.jira?.apiToken, process.env.JIRA_API_TOKEN];
+    const found = [];
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed && trimmed.length >= 8 && !found.includes(trimmed))
+            found.push(trimmed);
+    }
+    return found;
+}
+function redact(text, secrets) {
+    let out = text;
+    for (const secret of secrets)
+        out = out.split(secret).join("[redacted]");
+    return out;
+}

package/dist/workflow.js

@@ -5,6 +5,12 @@ import { jobBasename, packageRoot } from "./paths.js";
 const FACTORY_DIRECTIVE = /^<!--\s*factory:\s*(prompts\/factory\/[a-z0-9-]+\.md)\s*-->/;
 const WORKFLOW_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const FEATURE_PROMPTS = 7;
+const INVESTIGATION_PROMPTS = 1;
+/** Prompt files Kiln rewrites before launch. A mismatch refuses the launch. */
+const PROMPT_COUNTS = {
+    feature: FEATURE_PROMPTS,
+    investigation: INVESTIGATION_PROMPTS,
+};
 /**
  * Values Kiln can pass into a workflow. A workflow's inputSchema lists the
  * ones it uses. `description` and `acceptance` stay so
@@ -34,6 +40,10 @@ export function assertWorkflowName(name) {
  * to an absolute file under the kiln directory: the Kiln preamble plus the
  * verbatim factory prompt. The content hash is part of the filename, so a
  * prompt edit changes the path yak caches on.
+ *
+ * A preamble that starts with `<!-- factory: prompts/factory/<file>.md -->`
+ * is combined with that factory body. A prompt without that directive is
+ * stored as itself. `prompts/kiln/investigation.md` uses the second form.
  */
 export function materializeWorkflow(kilnDir, jobId, workflowName) {
     const sourcePath = assertWorkflowName(workflowName);
@@ -47,8 +57,9 @@ export function materializeWorkflow(kilnDir, jobId, workflowName) {
         const absolute = writeCombinedPrompt(rel, destDir);
         return `file: ${yamlDoubleQuote(absolute)}`;
     });
-    if (workflowName === "feature" && count !== FEATURE_PROMPTS) {
-        throw new Error(`Feature workflow has ${count} prompts/kiln refs; expected ${FEATURE_PROMPTS}. Refusing to launch a partial prompt set.`);
+    const expected = PROMPT_COUNTS[workflowName];
+    if (expected !== undefined && count !== expected) {
+        throw new Error(`${workflowName} workflow has ${count} prompts/kiln refs; expected ${expected}. Refusing to launch a partial prompt set.`);
     }
     if (rendered.includes("file: prompts/")) {
         throw new Error(`Rendered ${workflowName} workflow still has a checkout-relative prompt path.`);
@@ -70,6 +81,10 @@ export function workflowInputs(workflowYaml, input) {
     }
     return out;
 }
+/** True when the workflow runs the repo test command. Investigation does not. */
+export function workflowNeedsTestCommand(workflowYaml) {
+    return /\bKILN_TEST\b/.test(workflowYaml) || workflowYaml.includes("KILN_VERIFY_WRAPPER");
+}
 function declaredInputProperties(yaml) {
     const at = yaml.indexOf("\ninputSchema:");
     const start = at >= 0 ? at : yaml.startsWith("inputSchema:") ? 0 : -1;
@@ -92,17 +107,20 @@ function writeCombinedPrompt(preambleRel, destDir) {
     const preamblePath = join(root, preambleRel);
     const preamble = readFileSync(preamblePath, "utf8");
     const directive = preamble.match(FACTORY_DIRECTIVE);
+    let combined;
     if (!directive?.[1]) {
-        throw new Error(`${preambleRel} must start with <!-- factory: prompts/factory/<file>.md -->`);
+        combined = `${preamble.trimEnd()}\n`;
     }
-    const factoryRel = directive[1];
-    const factoryPath = join(root, factoryRel);
-    const factoryRoot = join(root, "prompts", "factory") + sep;
-    if (!factoryPath.startsWith(factoryRoot)) {
-        throw new Error(`${preambleRel} factory path ${factoryRel} escapes prompts/factory.`);
+    else {
+        const factoryRel = directive[1];
+        const factoryPath = join(root, factoryRel);
+        const factoryRoot = join(root, "prompts", "factory") + sep;
+        if (!factoryPath.startsWith(factoryRoot)) {
+            throw new Error(`${preambleRel} factory path ${factoryRel} escapes prompts/factory.`);
+        }
+        const factory = readFileSync(factoryPath, "utf8");
+        combined = `${preamble.trimEnd()}\n\n${factory.trimStart()}`;
     }
-    const factory = readFileSync(factoryPath, "utf8");
-    const combined = `${preamble.trimEnd()}\n\n${factory.trimStart()}`;
     const digest = createHash("sha256").update(combined).digest("hex").slice(0, 16);
     const outPath = join(destDir, `${basename(preambleRel, ".md")}-${digest}.md`);
     writeFileSync(outPath, combined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/kiln",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Run a workflow on any registered repo. A markdown spec is the input.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "assets",
     "workflows",
     "prompts",
     "README.md"

package/prompts/kiln/investigation.md

@@ -0,0 +1,31 @@
+Kiln runs this investigation inside yak. The working directory is an isolated worktree of the repo at base SHA `{{input.baseRef}}`. That SHA is the commit to inspect. Do not guess a branch name.
+
+Explore the tree and answer the questions in the spec. You may run commands and scripts. You must not change product code. Do not create, modify, or delete files. Do not commit, push, or open a pull request. Do not run formatters, package installs, or anything else that writes. Read-only git and file inspection are allowed. This step has no Write or Edit tool.
+
+Do not write a findings file. Return JSON with one string field, `markdown`. Kiln stores that markdown after a person approves it, and later jobs read it. The markdown is the whole document, not a fragment.
+
+Use these headings, in this order, spelled exactly:
+
+# Findings: {{input.title}}
+
+## Questions
+
+The questions the spec asks, as a list.
+
+## Answers
+
+One subsection per question. State the answer, then the evidence. Evidence is file paths and command output you actually observed in this worktree. Do not invent paths or output. If you did not run a command, do not claim you did.
+
+## Unconfirmed
+
+What you could not confirm, and what you looked at. Write "None." when nothing is left open.
+
+## Implications for dependent tickets
+
+What a later ticket should rely on, and what it must not assume.
+
+Spec title: {{input.title}}
+
+{{input.spec}}
+
+Launch id: {{input.runNonce}}

package/workflows/investigation.yaml

@@ -0,0 +1,67 @@
+# One Kiln investigation, run by yak (@lchase/yak).
+#
+# A spike, probe, or research ticket. The agent explores the worktree and
+# returns a findings document. A person approves or rejects it. There is no
+# build, review, verify, or land step, and Kiln does not open a pull request
+# for this workflow, whatever the repo's deliver mode is.
+#
+# The agent artifact is `findings`: `{ "markdown": "<document>" }`.
+# The document uses these headings, in order:
+#   # Findings: <title>
+#   ## Questions
+#   ## Answers          (each answer includes evidence: file paths and command output)
+#   ## Unconfirmed
+#   ## Implications for dependent tickets
+# On approve, Kiln copies that markdown to `<kilnDir>/findings/<jobId>.md`.
+# A later job that depends on this one receives the file as a
+# `## Findings from <title>` section in the spec yak sees.
+#
+# `adapter: "mock"` reads `test/fixtures/kiln-investigation/explore.json`
+# from the checkout. The gate has no fixture.
+# Prompt paths are rewritten to absolute files under the kiln directory
+# before launch, same as workflows/feature.yaml. This prompt has no factory
+# directive; it is stored as itself.
+name: kiln-investigation
+version: "1"
+inputSchema:
+  inline:
+    type: object
+    additionalProperties: false
+    properties:
+      title: { type: string }
+      spec: { type: string }
+      runNonce: { type: string }
+      baseRef: { type: string }
+    required: [title, spec, runNonce, baseRef]
+steps:
+  - id: explore
+    needs: [input]
+    agent:
+      model: opus
+      prompt:
+        file: prompts/kiln/investigation.md
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            markdown: { type: string, minLength: 1 }
+          required: [markdown]
+      # Bash can run read-only commands. File-editing tools are omitted.
+      # The prompt forbids any command that writes.
+      tools: [Read, Grep, Glob, Bash]
+    produces: findings
+
+  - id: approve
+    needs: [input, findings]
+    gate:
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            decision: { type: string, enum: [approve, reject] }
+          required: [decision]
+      render:
+        inline: "Approve findings for \"{{input.title}}\"?\n\n{{findings.markdown}}"
+    produces: approval