@lchase/kiln 0.0.0-stage → 0.1.0

package/dist/reconcile.js

@@ -0,0 +1,123 @@
+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.
+ */
+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. */
+export function isDone(job) {
+    if (!isLanded(job))
+        return false;
+    if ((job.deliver ?? "local") !== "pr")
+        return true;
+    return job.delivery?.merged === true || job.delivery?.prState === "MERGED";
+}
+function landedState(job) {
+    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.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 (!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,157 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+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)}`;
+}
+export function renderStatus(observation, jobId) {
+    const jobs = jobId ? observation.jobs.filter((job) => job.jobId === jobId) : observation.jobs;
+    if (jobId && jobs.length === 0) {
+        throw new Error(`No job ${jobId}.`);
+    }
+    if (jobs.length === 0)
+        return "no jobs\n";
+    const lines = [];
+    for (const job of jobs) {
+        if (job.error) {
+            lines.push(`${job.jobId}  invalid: ${job.error}`);
+            continue;
+        }
+        const state = jobState(job, observation);
+        const run = job.run ? `  run ${job.run.runId}` : "";
+        const branch = job.run && (state === "done" || state === "in-review") ? `  branch yak/${job.run.runId}` : "";
+        const pr = prSuffix(job, state);
+        lines.push(`${job.jobId}  ${job.repo}  ${job.workflow}  ${state}${run}${branch}${pr}`);
+        if (job.source)
+            lines.push(`  source ${job.source.kind} ${job.source.ref}`);
+        if (state === "in-review" && !job.delivery?.prNumber) {
+            lines.push("  pull request not opened yet");
+        }
+        if (state === "failed" && job.delivery?.error) {
+            lines.push(`  ${job.delivery.error}`);
+        }
+        if (state === "failed" && job.delivery?.prState === "CLOSED" && job.delivery.prNumber) {
+            lines.push(`  pull request #${job.delivery.prNumber} was closed without merging`);
+        }
+        if (job.delivery?.viewError && (state === "in-review" || state === "done")) {
+            lines.push(`  could not read pull request: ${job.delivery.viewError}`);
+        }
+        if (state === "failed" && job.launchFailed && job.logPath) {
+            lines.push(`  log ${job.logPath}`);
+        }
+        if (state === "failed" && job.launchError) {
+            lines.push(`  ${job.launchError}`);
+        }
+        if (state === "failed" && job.run?.status === "ok" && !job.run.gateDecision) {
+            lines.push("  no readable approval decision");
+        }
+        if (state === "dead" && job.run) {
+            lines.push(`  fix: cd ${shellQuote(job.run.checkout)} && ${yakInvocation("cancel", job.run.runId)}`);
+        }
+        if (state === "blocked") {
+            for (const line of blockedLines(job, observation))
+                lines.push(line);
+        }
+        if (state === "needs-human" && job.run) {
+            for (const gate of job.run.gates) {
+                lines.push(`  gate ${gate.stepId}: ${gate.prompt}`);
+                appendGateCommands(lines, job, gate);
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function prSuffix(job, state) {
+    const url = job.delivery?.prUrl;
+    if (!url)
+        return "";
+    if (state !== "in-review" && state !== "done" && state !== "failed")
+        return "";
+    return `  pr ${url}`;
+}
+function blockedLines(job, observation) {
+    const lines = [];
+    for (const dep of job.dependsOn) {
+        const upstream = observation.jobs.find((candidate) => candidate.jobId === dep);
+        if (!upstream) {
+            lines.push(`  blocked on missing job ${dep}`);
+            continue;
+        }
+        if (job.stack) {
+            if (!isLanded(upstream))
+                lines.push(`  waiting for ${dep} to land`);
+            continue;
+        }
+        if (isDone(upstream))
+            continue;
+        const number = upstream.delivery?.prNumber;
+        if (number && !upstream.delivery?.merged && upstream.delivery?.prState !== "CLOSED") {
+            lines.push(`  waiting for PR #${number} to merge`);
+            continue;
+        }
+        if ((upstream.deliver ?? "local") === "pr" && isLanded(upstream)) {
+            lines.push(`  waiting for ${dep} to open a pull request`);
+        }
+    }
+    return lines;
+}
+function appendGateCommands(lines, job, gate) {
+    const choices = gate.choices?.length ? gate.choices : ["approve", "reject"];
+    if (choices.includes("approve"))
+        lines.push(`  approve: kiln approve ${job.jobId}`);
+    if (choices.includes("reject"))
+        lines.push(`  reject: kiln reject ${job.jobId}`);
+}
+export function renderTick(observation, actions, launches, delivers = []) {
+    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 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) {
+        lines.push("nothing to launch");
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/schemas.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+/**
+ * Kiln config file. `repos` is an open map: any name, not a fixed set.
+ * `path` is absolute, relative to the config file's directory, or `~`.
+ * `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.
+     */
+    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. 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",
+];

package/dist/truncate-output.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import { writeSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+/** Last lines of verify output kept for later prompts. */
+export const VERIFY_MAX_LINES = 200;
+/** Last bytes of verify output kept for later prompts, after the line cut. */
+export const VERIFY_MAX_BYTES = 20 * 1024;
+const RAW_CAP = 1024 * 1024;
+/**
+ * Keep the tail of a verify stream so a long test log cannot land whole in
+ * the next prompt. A cut is marked on the first line.
+ */
+export function truncateCaptured(text, stream) {
+    const lined = lastLines(text, VERIFY_MAX_LINES);
+    const tailed = lastBytes(lined.text, VERIFY_MAX_BYTES);
+    if (!lined.cut && !tailed.cut)
+        return text;
+    const note = `[truncated: showing the last ${VERIFY_MAX_LINES} lines or ${VERIFY_MAX_BYTES} bytes of ${stream}]\n`;
+    return note + tailed.text;
+}
+function lastLines(text, maxLines) {
+    if (text.length === 0)
+        return { text, cut: false };
+    const trailingNewline = text.endsWith("\n");
+    const parts = text.split("\n");
+    if (trailingNewline)
+        parts.pop();
+    if (parts.length <= maxLines)
+        return { text, cut: false };
+    const kept = parts.slice(-maxLines);
+    return { text: kept.join("\n") + (trailingNewline ? "\n" : ""), cut: true };
+}
+function lastBytes(text, maxBytes) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= maxBytes)
+        return { text, cut: false };
+    let start = buf.length - maxBytes;
+    while (start < buf.length && (buf[start] & 0xc0) === 0x80)
+        start += 1;
+    return { text: buf.subarray(start).toString("utf8"), cut: true };
+}
+function capTail(current, chunk, cap) {
+    let piece = chunk;
+    let cut = false;
+    if (Buffer.byteLength(piece, "utf8") > cap) {
+        piece = lastBytes(piece, cap).text;
+        cut = true;
+        current = "";
+    }
+    const next = current + piece;
+    if (Buffer.byteLength(next, "utf8") <= cap)
+        return { text: next, cut };
+    return { text: lastBytes(next, cap).text, cut: true };
+}
+/**
+ * `process.stdout.write` queues behind an in-flight write. `process.exit`
+ * leaves that queue in the process and the parent's `close` handler never
+ * sees it. A blocking write puts the bytes in the pipe first.
+ */
+function writeAll(fd, text) {
+    if (text.length === 0)
+        return;
+    const buf = Buffer.from(text);
+    let offset = 0;
+    while (offset < buf.length) {
+        let wrote = 0;
+        try {
+            wrote = writeSync(fd, buf, offset);
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+            if (code === "EAGAIN" || code === "EWOULDBLOCK")
+                continue;
+            throw error;
+        }
+        if (wrote <= 0)
+            return;
+        offset += wrote;
+    }
+}
+function isDirectRun() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    return import.meta.url === pathToFileURL(entry).href;
+}
+function main() {
+    const command = process.env.KILN_TEST;
+    if (!command?.trim()) {
+        writeAll(2, "KILN_TEST is empty\n");
+        process.exit(1);
+    }
+    const child = spawn(command, { shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        writeAll(1, truncateCaptured(stdout, "stdout"));
+        writeAll(2, truncateCaptured(stderr, "stderr"));
+        process.exit(code);
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+        stdout = capTail(stdout, chunk, RAW_CAP).text;
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr = capTail(stderr, chunk, RAW_CAP).text;
+    });
+    child.on("error", (error) => {
+        stderr += `${error.message}\n`;
+        finish(1);
+    });
+    child.on("close", (code) => {
+        finish(code ?? 1);
+    });
+}
+if (isDirectRun())
+    main();

package/dist/workflow.js

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+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;
+/**
+ * Values Kiln can pass into a workflow. A workflow's inputSchema lists the
+ * ones it uses. `description` and `acceptance` stay so
+ * `workflows/feature.yaml` can keep its schema: both are the spec text.
+ */
+const INPUT_VALUES = {
+    title: (input) => input.title,
+    spec: (input) => input.specText,
+    baseRef: (input) => input.baseRef,
+    runNonce: (input) => input.runNonce,
+    description: (input) => input.specText,
+    acceptance: (input) => input.specText,
+};
+export function assertWorkflowName(name) {
+    if (!WORKFLOW_NAME.test(name)) {
+        throw new Error(`Workflow name ${JSON.stringify(name)} must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens.`);
+    }
+    const path = join(packageRoot(), "workflows", `${name}.yaml`);
+    if (!existsSync(path)) {
+        throw new Error(`Unknown workflow ${name}. Expected ${path}.`);
+    }
+    return path;
+}
+/**
+ * Yak reads `prompt.file` with `path.resolve(cwd, file)`, and Kiln launches
+ * yak with cwd set to the product checkout. Rewrite `prompts/kiln/<name>.md`
+ * 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.
+ */
+export function materializeWorkflow(kilnDir, jobId, workflowName) {
+    const sourcePath = assertWorkflowName(workflowName);
+    const source = readFileSync(sourcePath, "utf8");
+    const destDir = join(kilnDir, "rendered", jobBasename(jobId));
+    mkdirSync(destDir, { recursive: true });
+    let count = 0;
+    const rendered = source.replace(/file: prompts\/kiln\/([a-z0-9-]+)\.md/g, (_full, name) => {
+        count += 1;
+        const rel = `prompts/kiln/${name}.md`;
+        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.`);
+    }
+    if (rendered.includes("file: prompts/")) {
+        throw new Error(`Rendered ${workflowName} workflow still has a checkout-relative prompt path.`);
+    }
+    const workflowPath = join(destDir, `${workflowName}.yaml`);
+    writeFileSync(workflowPath, rendered);
+    return workflowPath;
+}
+/** The subset of {@link INPUT_VALUES} that this workflow's inputSchema declares. */
+export function workflowInputs(workflowYaml, input) {
+    const names = declaredInputProperties(workflowYaml);
+    const out = {};
+    for (const name of names) {
+        const fill = INPUT_VALUES[name];
+        if (!fill) {
+            throw new Error(`Workflow input "${name}" is not a Kiln launch input. Kiln passes title, spec, baseRef, and runNonce (and KILN_TEST in the environment).`);
+        }
+        out[name] = fill(input);
+    }
+    return out;
+}
+function declaredInputProperties(yaml) {
+    const at = yaml.indexOf("\ninputSchema:");
+    const start = at >= 0 ? at : yaml.startsWith("inputSchema:") ? 0 : -1;
+    if (start < 0) {
+        throw new Error("Workflow has no inputSchema. Kiln passes title, spec, baseRef, and runNonce.");
+    }
+    const slice = yaml.slice(start);
+    const props = slice.match(/\n[^\n]*properties:\n([\s\S]*?)\n[^\n]*required:/);
+    if (!props?.[1]) {
+        throw new Error("Workflow inputSchema has no properties block.");
+    }
+    const names = [...props[1].matchAll(/(?:^|\n)\s+([A-Za-z_][A-Za-z0-9_-]*):/g)].map((match) => match[1] ?? "");
+    if (names.length === 0 || names.some((name) => name.length === 0)) {
+        throw new Error("Workflow inputSchema lists no input properties.");
+    }
+    return names;
+}
+function writeCombinedPrompt(preambleRel, destDir) {
+    const root = packageRoot();
+    const preamblePath = join(root, preambleRel);
+    const preamble = readFileSync(preamblePath, "utf8");
+    const directive = preamble.match(FACTORY_DIRECTIVE);
+    if (!directive?.[1]) {
+        throw new Error(`${preambleRel} must start with <!-- factory: prompts/factory/<file>.md -->`);
+    }
+    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");
+    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);
+    return outPath;
+}
+function yamlDoubleQuote(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lchase/kiln",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Run a workflow on any registered repo. A markdown spec is the input.",
+  "type": "module",
+  "bin": {
+    "kiln": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "workflows",
+    "prompts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lchase/kiln.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "kiln": "node dist/cli.js",
+    "prekiln": "npm run build",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "tsc -p tsconfig.json && tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@lchase/yak": "0.7.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "typescript": "^5.9.3"
+  }
+}