@lchase/kiln 0.6.0 → 0.7.0

package/dist/fs-browse.js

@@ -0,0 +1,113 @@
+import { closeSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { HttpError } from "./errors.js";
+/** A chosen markdown file returns this many lines, and no more of the body. */
+export const PREVIEW_LINES = 40;
+const PREVIEW_BYTES = 16 * 1024;
+export function homeReal(home = homedir()) {
+    try {
+        return realpathSync(resolve(home));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new HttpError(500, `Home directory is not available: ${message}`);
+    }
+}
+/**
+ * Absolute path of `target` after symlink resolution.
+ * Refuses anything outside `home`, and any hidden path segment.
+ */
+export function assertInsideHome(home, target) {
+    const root = homeReal(home);
+    const resolved = resolve(target);
+    let real;
+    try {
+        real = realpathSync(resolved);
+    }
+    catch {
+        throw new HttpError(404, `No such path ${resolved}.`);
+    }
+    if (real !== root && !real.startsWith(root + sep)) {
+        throw new HttpError(403, "Path is outside the home directory.");
+    }
+    const rel = relative(root, real);
+    if (rel !== "" && rel.split(sep).some((part) => part.startsWith("."))) {
+        throw new HttpError(403, "Hidden files are not listed.");
+    }
+    return real;
+}
+/** Directories and `.md` files under the home directory. A file returns a short preview. */
+export function browse(home, rawPath) {
+    const root = homeReal(home);
+    const requested = rawPath?.trim() ? rawPath : root;
+    const real = assertInsideHome(home, requested);
+    const stat = statSync(real);
+    if (stat.isDirectory())
+        return listDir(root, real);
+    if (stat.isFile())
+        return previewFile(real);
+    throw new HttpError(400, "Only directories and .md files can be opened.");
+}
+function listDir(root, dir) {
+    const names = readdirSync(dir);
+    const entries = [];
+    for (const name of names) {
+        if (name.startsWith("."))
+            continue;
+        const path = join(dir, name);
+        let real;
+        let info;
+        try {
+            info = statSync(path);
+            real = realpathSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (real !== root && !real.startsWith(root + sep))
+            continue;
+        const rel = relative(root, real);
+        if (rel !== "" && rel.split(sep).some((part) => part.startsWith(".")))
+            continue;
+        if (info.isDirectory())
+            entries.push({ name, path: real, kind: "dir" });
+        else if (info.isFile() && name.toLowerCase().endsWith(".md"))
+            entries.push({ name, path: real, kind: "file" });
+    }
+    entries.sort((left, right) => {
+        if (left.kind !== right.kind)
+            return left.kind === "dir" ? -1 : 1;
+        return left.name.localeCompare(right.name);
+    });
+    return { path: dir, parent: parentInside(root, dir), kind: "dir", entries };
+}
+function parentInside(root, dir) {
+    if (dir === root)
+        return null;
+    const parent = dirname(dir);
+    if (parent !== root && !parent.startsWith(root + sep))
+        return null;
+    return parent;
+}
+function previewFile(path) {
+    if (!basename(path).toLowerCase().endsWith(".md")) {
+        throw new HttpError(400, "Only .md files can be previewed.");
+    }
+    const size = statSync(path).size;
+    const fd = openSync(path, "r");
+    try {
+        const buf = Buffer.alloc(PREVIEW_BYTES);
+        const read = readSync(fd, buf, 0, PREVIEW_BYTES, 0);
+        const lines = buf.subarray(0, read).toString("utf8").split(/\r?\n/);
+        return {
+            path,
+            kind: "file",
+            preview: lines.slice(0, PREVIEW_LINES).join("\n"),
+            truncated: lines.length > PREVIEW_LINES || size > read,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/host.js

@@ -3,6 +3,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { realPullRequestFeedback } from "./feedback.js";
+import { isPublishableBranch } from "./pr-names.js";
 /**
  * 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
@@ -82,10 +83,15 @@ export const realGitRemote = {
     },
     publishBranch(checkout, source, target, baseBranch) {
         assertYakBranch(source, baseBranch);
-        assertYakBranch(target, baseBranch);
+        if (target === baseBranch || target === `refs/heads/${baseBranch}`) {
+            throw new HostError(`Refusing to push ${target}: that is the base branch.`);
+        }
         if (source.includes("+") || target.includes("+")) {
             throw new HostError(`Refusing to push ${target}: kiln does not force-push.`);
         }
+        if (!isPublishableBranch(target)) {
+            throw new HostError(`Refusing to push ${target}: that branch name is not safe.`);
+        }
         const result = gitResult(checkout, ["push", "origin", `refs/heads/${source}:refs/heads/${target}`]);
         if (result.status !== 0) {
             throw new HostError(`Could not push ${source} onto ${target}: ${result.stderr.trim() || "git push failed"}`);

package/dist/intake/file.js

@@ -22,6 +22,7 @@ export function addFromFile(config, input) {
         specText: text,
         title,
         dependsOn: input.dependsOn,
+        ...(input.issue !== undefined ? { issue: input.issue } : {}),
         ...(input.stack ? { stack: true } : {}),
         source: { kind: "file", ref: source },
         ...(input.now ? { now: input.now } : {}),

package/dist/intake/jira.js

@@ -1,9 +1,8 @@
 import { assertCanStack, listValidJobs, renderAddedJob, writeJob } from "../jobs.js";
+import { ISSUE_KEY } from "../schemas.js";
 import { assertWorkflowName } from "../workflow.js";
 import { INVESTIGATION_WORKFLOW } from "../findings.js";
 import { typeLooksLikeSpike, workflowForSpike } from "./tickets.js";
-/** Jira issue keys, stored and matched in uppercase (`PROJ-123`). */
-const ISSUE_KEY = /^[A-Z][A-Z0-9]+-\d+$/;
 const ENV_BASE_URL = "JIRA_BASE_URL";
 const ENV_EMAIL = "JIRA_EMAIL";
 const ENV_API_TOKEN = "JIRA_API_TOKEN";
@@ -13,6 +12,15 @@ const ENV_API_TOKEN = "JIRA_API_TOKEN";
  */
 export async function addFromJira(config, input) {
     const key = normalizeIssueKey(input.key);
+    if (input.issue !== undefined) {
+        const explicit = input.issue.trim().toUpperCase();
+        if (!ISSUE_KEY.test(explicit)) {
+            throw new Error(`Issue key ${JSON.stringify(input.issue)} must match KEY-123.`);
+        }
+        if (explicit !== key) {
+            throw new Error(`--issue ${explicit} does not match --jira ${key}.`);
+        }
+    }
     assertKnownRepo(config, input.repo);
     assertWorkflowName(input.workflow);
     const existing = existingJiraJob(config, key);
@@ -43,7 +51,7 @@ export async function addFromJira(config, input) {
         acceptanceMarkdown: acceptanceMarkdown(issue.acceptance),
     });
     assertCanStack(input.repo, dependsOn, input.stack, listValidJobs(config));
-    const title = input.title?.trim() || `${key}: ${issue.summary}`;
+    const title = input.title?.trim() || issue.summary.trim();
     if (!title) {
         throw new Error("Job title is empty. Pass --title.");
     }
@@ -67,6 +75,7 @@ export async function addFromJira(config, input) {
         repo: input.repo,
         specText: safeSpec,
         title: redactSecrets(title, credentials),
+        issue: key,
         dependsOn,
         ...(input.stack ? { stack: true } : {}),
         source: { kind: "jira", ref: key },
@@ -382,7 +391,13 @@ function renderExisting(job) {
     return [`exists ${job.id}`, `repo ${job.repo}`, `workflow ${job.workflow}`, `source jira ${ref}`, ""].join("\n");
 }
 function renderDryRun(input) {
-    const lines = [`dry-run ${input.key}`, `repo ${input.repo}`, `workflow ${input.workflow}`, `title ${input.title}`];
+    const lines = [
+        `dry-run ${input.key}`,
+        `repo ${input.repo}`,
+        `workflow ${input.workflow}`,
+        `title ${input.title}`,
+        `issue ${input.key}`,
+    ];
     if (input.dependsOn.length > 0)
         lines.push(`dependsOn ${input.dependsOn.join(", ")}`);
     lines.push(`source jira ${input.key}`, "spec:", input.specText.trimEnd(), "created nothing", "");

package/dist/intake/prompt.js

@@ -40,6 +40,7 @@ export function addFromPrompt(config, input) {
         specText: text,
         title,
         dependsOn: input.dependsOn,
+        ...(input.issue !== undefined ? { issue: input.issue } : {}),
         ...(input.stack ? { stack: true } : {}),
         source: { kind: "prompt", ref: fromStdin ? "stdin" : "inline" },
         ...(input.now ? { now: input.now } : {}),

package/dist/intake/tickets.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "n
 import { basename, dirname, join, resolve } from "node:path";
 import { INVESTIGATION_WORKFLOW } from "../findings.js";
 import { listValidJobs, newJobId, writeJob } from "../jobs.js";
+import { ISSUE_KEY } from "../schemas.js";
 import { assertWorkflowName } from "../workflow.js";
 /** Context files larger than this are named in the spec instead of copied in. */
 export const CONTEXT_INLINE_LIMIT = 40 * 1024;
@@ -125,6 +126,7 @@ export function importTickets(config, input) {
                 repo: input.repo,
                 specText: composeSpec(write.ticket.text, context),
                 title: write.ticket.title,
+                ...(write.ticket.issue ? { issue: write.ticket.issue } : {}),
                 dependsOn: write.dependsOn,
                 ...(input.stack ? { stack: true } : {}),
                 source: { kind: "tickets", ref: write.ticket.path },
@@ -133,9 +135,19 @@ export function importTickets(config, input) {
             });
         }
     }
+    const jobs = rows.map((row) => ({
+        status: row.status,
+        label: row.label,
+        title: row.title,
+        workflow: row.workflow,
+        dependsOn: row.depLabels,
+        ...(row.jobId ? { jobId: row.jobId } : {}),
+    }));
     return {
         report: renderImport(dirAbs, input.repo, rows, input.dryRun),
         warnings,
+        ids: input.dryRun ? [] : writes.map((write) => write.id),
+        jobs,
     };
 }
 function resolveTicketDir(cwd, dir) {
@@ -265,12 +277,18 @@ function parseTicket(dirAbs, file) {
     if (!title) {
         throw new Error(`Ticket ${file} has no title. Expected a "# NN: Title" heading or front matter title.`);
     }
+    const headingIssue = issueKeyIn(title);
+    if (meta.issue && headingIssue && meta.issue !== headingIssue) {
+        throw new Error(`Ticket ${file} issue ${meta.issue} does not match the heading issue ${headingIssue}.`);
+    }
+    const issue = meta.issue ?? headingIssue;
     return {
         file,
         path,
         label,
         number,
         title,
+        ...(issue ? { issue } : {}),
         text,
         blockedBy: dedupeRefs([...meta.blockedBy, ...bodyDeps]),
         spike: looksLikeSpike(title, text, meta.type),
@@ -286,6 +304,7 @@ function parseFrontMatter(yaml) {
     const lines = yaml.split(/\r?\n/);
     let title;
     let type;
+    let issue;
     const blockedBy = [];
     let listKey;
     for (const line of lines) {
@@ -306,6 +325,16 @@ function parseFrontMatter(yaml) {
             title = unquote(value);
         else if (key === "type")
             type = unquote(value);
+        else if (key === "issue") {
+            const raw = unquote(value).trim();
+            if (!raw)
+                throw new Error("front matter issue is empty");
+            const keyNorm = raw.toUpperCase();
+            if (!ISSUE_KEY.test(keyNorm)) {
+                throw new Error(`front matter issue ${JSON.stringify(raw)} is not a KEY-123 identifier.`);
+            }
+            issue = keyNorm;
+        }
         else if (key === "blocked-by") {
             if (!value.trim())
                 listKey = "blocked-by";
@@ -313,7 +342,7 @@ function parseFrontMatter(yaml) {
                 blockedBy.push(...refsFromScalar(value));
         }
     }
-    return { title: title?.trim() || undefined, type: type?.trim() || undefined, blockedBy };
+    return { title: title?.trim() || undefined, type: type?.trim() || undefined, ...(issue ? { issue } : {}), blockedBy };
 }
 function refsFromScalar(raw) {
     const value = unquote(raw.trim());
@@ -371,6 +400,17 @@ function blockedByFromBody(body, filename) {
     }
     return refs;
 }
+/** A leading `ABC-123:`, `ABC-123 `, or `[ABC-123]` on a title. `01: Title` is not an issue. */
+function issueKeyIn(value) {
+    if (!value)
+        return undefined;
+    const match = /^\s*(?:\[([A-Za-z][A-Za-z0-9]+-\d+)\]|([A-Za-z][A-Za-z0-9]+-\d+):|([A-Za-z][A-Za-z0-9]+-\d+)\s+)/.exec(value);
+    const raw = match?.[1] ?? match?.[2] ?? match?.[3];
+    if (!raw)
+        return undefined;
+    const key = raw.toUpperCase();
+    return ISSUE_KEY.test(key) ? key : undefined;
+}
 function headingTitle(body) {
     for (const line of body.split(/\r?\n/)) {
         const heading = /^#\s+(.+?)\s*$/.exec(line);

package/dist/intake-http.js

@@ -0,0 +1,201 @@
+import { isAbsolute, resolve } from "node:path";
+import { homedir } from "node:os";
+import { HttpError } from "./errors.js";
+import { assertInsideHome } from "./fs-browse.js";
+import { addFromFile } from "./intake/file.js";
+import { addFromJira } from "./intake/jira.js";
+import { addFromPrompt } from "./intake/prompt.js";
+import { importTickets } from "./intake/tickets.js";
+import { parseIssueKey } from "./schemas.js";
+/**
+ * `POST /api/jobs`. The body is the CLI intake, and the call goes through
+ * `addFromPrompt`, `addFromFile`, `importTickets`, or `addFromJira`.
+ */
+export async function intakeJobs(config, body, home = homedir()) {
+    const request = parseIntake(body);
+    try {
+        return await runIntake(config, request, home);
+    }
+    catch (error) {
+        if (error instanceof HttpError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new HttpError(400, message);
+    }
+}
+async function runIntake(config, request, home) {
+    const shared = {
+        workflow: request.workflow,
+        repo: request.repo,
+        ...(request.title !== undefined ? { title: request.title } : {}),
+        ...(request.issue !== undefined ? { issue: request.issue } : {}),
+        dependsOn: request.after,
+        ...(request.stack ? { stack: true } : {}),
+    };
+    if (request.source.kind === "prompt") {
+        if (request.dryRun)
+            throw new HttpError(400, "Dry-run is only supported for a tickets import.");
+        if (request.source.text === "-") {
+            throw new HttpError(400, "Pass the prompt text in source.text. Serve does not read stdin.");
+        }
+        const written = addFromPrompt(config, { ...shared, prompt: request.source.text });
+        return { ids: [written.job.id] };
+    }
+    if (request.source.kind === "spec") {
+        if (request.dryRun)
+            throw new HttpError(400, "Dry-run is only supported for a tickets import.");
+        const specPath = absoluteInside(home, request.source.path, "Spec path");
+        const written = addFromFile(config, { ...shared, specPath, cwd: process.cwd() });
+        return { ids: [written.job.id] };
+    }
+    if (request.source.kind === "jira") {
+        if (request.dryRun)
+            throw new HttpError(400, "Dry-run is only supported for a tickets import.");
+        const result = await addFromJira(config, { ...shared, key: request.source.key, dryRun: false });
+        return {
+            ids: result.job ? [result.job.id] : [],
+            created: result.created,
+            ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        };
+    }
+    const dir = absoluteInside(home, request.source.dir, "Tickets directory");
+    const contextPath = request.source.context
+        ? absoluteInside(home, request.source.context, "Context path")
+        : undefined;
+    const result = importTickets(config, {
+        dir,
+        repo: request.repo,
+        workflow: request.workflow,
+        ...(contextPath ? { contextPath } : {}),
+        dryRun: request.dryRun,
+        ...(request.stack ? { stack: true } : {}),
+        cwd: process.cwd(),
+    });
+    return {
+        ids: result.ids,
+        jobs: result.jobs,
+        report: result.report,
+        ...(request.dryRun ? { dryRun: true } : {}),
+        ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+    };
+}
+function parseIntake(body) {
+    const record = object(body, "Request body must be a JSON object.");
+    const repo = requiredString(record, "repo", "Name a repo.");
+    const workflow = requiredString(record, "workflow", "Name a workflow.");
+    const title = optionalString(record, "title", "title must be a string.");
+    const after = stringList(record.after, "after must be a list of job ids.");
+    const stack = optionalBoolean(record.stack, "stack must be a boolean.");
+    const dryRun = optionalBoolean(record.dryRun, "dryRun must be a boolean.") ?? false;
+    const source = parseSource(record.source);
+    const issue = parseIssueField(record.issue);
+    if (source.kind === "tickets" && title !== undefined) {
+        throw new HttpError(400, "A tickets import does not take a title. Each file has its own.");
+    }
+    if (source.kind === "tickets" && issue !== undefined) {
+        throw new HttpError(400, "A tickets import does not take an issue. Each file has its own.");
+    }
+    if (source.kind === "tickets" && after.length > 0) {
+        throw new HttpError(400, "A tickets import does not take after. Blocked-by in the files sets dependencies.");
+    }
+    return {
+        repo,
+        workflow,
+        ...(title !== undefined ? { title } : {}),
+        ...(issue !== undefined ? { issue } : {}),
+        after,
+        ...(stack ? { stack: true } : {}),
+        dryRun,
+        source,
+    };
+}
+/** Same `KEY-123` rule as `kiln add --issue`. A blank field is omitted. */
+function parseIssueField(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new HttpError(400, "issue must be a string.");
+    if (!value.trim())
+        return undefined;
+    try {
+        return parseIssueKey(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new HttpError(400, message);
+    }
+}
+function parseSource(value) {
+    const source = object(value, "Name a source: prompt, spec, tickets, or jira.");
+    const kind = source.kind;
+    if (kind === "prompt") {
+        if (typeof source.text !== "string")
+            throw new HttpError(400, "Prompt text must be a string.");
+        return { kind, text: source.text };
+    }
+    if (kind === "spec") {
+        if (typeof source.path !== "string")
+            throw new HttpError(400, "Spec path must be a string.");
+        return { kind, path: source.path };
+    }
+    if (kind === "tickets") {
+        if (typeof source.dir !== "string")
+            throw new HttpError(400, "Tickets directory must be a string.");
+        if (source.context !== undefined && typeof source.context !== "string") {
+            throw new HttpError(400, "Context path must be a string.");
+        }
+        return {
+            kind,
+            dir: source.dir,
+            ...(typeof source.context === "string" ? { context: source.context } : {}),
+        };
+    }
+    if (kind === "jira") {
+        if (typeof source.key !== "string")
+            throw new HttpError(400, "Jira key must be a string.");
+        return { kind, key: source.key };
+    }
+    throw new HttpError(400, "Source kind must be prompt, spec, tickets, or jira.");
+}
+function absoluteInside(home, path, label) {
+    if (!path.trim() || !isAbsolute(path)) {
+        throw new HttpError(400, `${label} must be an absolute path.`);
+    }
+    const absolute = resolve(path);
+    assertInsideHome(home, absolute);
+    return absolute;
+}
+function object(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new HttpError(400, message);
+    }
+    return value;
+}
+function requiredString(record, key, message) {
+    const value = record[key];
+    if (typeof value !== "string" || !value.trim())
+        throw new HttpError(400, message);
+    return value.trim();
+}
+function optionalString(record, key, message) {
+    if (record[key] === undefined)
+        return undefined;
+    if (typeof record[key] !== "string")
+        throw new HttpError(400, message);
+    return record[key];
+}
+function optionalBoolean(value, message) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new HttpError(400, message);
+    return value;
+}
+function stringList(value, message) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) {
+        throw new HttpError(400, message);
+    }
+    return value.map((item) => item.trim());
+}

package/dist/jobs.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { basename, isAbsolute, join } from "node:path";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { jobBasename } from "./paths.js";
-import { JobSchema } from "./schemas.js";
+import { JobSchema, parseIssueKey } from "./schemas.js";
 import { assertWorkflowName } from "./workflow.js";
 export function newJobId(now = new Date()) {
     const stamp = now.toISOString().replace(/[-:TZ.]/g, "").slice(0, 14);
@@ -52,6 +52,7 @@ export function writeJob(config, input) {
     if (!title) {
         throw new Error("Job title is empty. Pass --title.");
     }
+    const issue = input.issue !== undefined ? parseIssueKey(input.issue) : undefined;
     const now = input.now ?? new Date();
     const id = input.id ?? newJobId(now);
     const dependsOn = normalizedDepends(input.dependsOn);
@@ -80,6 +81,7 @@ export function writeJob(config, input) {
         title,
         ...(dependsOn.length > 0 ? { dependsOn } : {}),
         ...(input.stack ? { stack: true } : {}),
+        ...(issue ? { issue } : {}),
         source: input.source,
         createdAt: now.toISOString(),
     });
@@ -90,6 +92,8 @@ export function writeJob(config, input) {
 }
 export function renderAddedJob(job, jsonPath) {
     const lines = [`added ${job.id}`, `repo ${job.repo}`, `workflow ${job.workflow}`, `spec ${job.spec}`];
+    if (job.issue)
+        lines.push(`issue ${job.issue}`);
     if (job.stack)
         lines.push("stack");
     if (job.source)

package/dist/pr-names.js

@@ -0,0 +1,116 @@
+/**
+ * Pull request title and remote branch for `deliver=pr`.
+ * Yak keeps the local branch `yak/<run-id>`. Kiln pushes that ref to a
+ * readable name and opens the pull request with `--head` set to it.
+ */
+export const DEFAULT_PR_TITLE = "[{issue}] {title}";
+/** Default remote branch when the job has an issue. Renders as `ABC-123-slug`. */
+export const DEFAULT_BRANCH_TEMPLATE = "{issue}-{slug}";
+export function stripIssuePrefix(title, issue) {
+    const trimmed = title.trim();
+    const escaped = issue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const patterns = [
+        new RegExp(`^\\[${escaped}\\]\\s*`),
+        new RegExp(`^${escaped}:\\s*`),
+        new RegExp(`^${escaped}\\s+`),
+    ];
+    for (const pattern of patterns) {
+        if (!pattern.test(trimmed))
+            continue;
+        const next = trimmed.replace(pattern, "").trim();
+        return next || trimmed;
+    }
+    return trimmed;
+}
+/**
+ * No issue: the title is unchanged, including when a repo template is set.
+ * With an issue: strip a leading `ABC-123:`, `ABC-123 `, or `[ABC-123]`
+ * so a Jira `KEY: summary` title is not applied twice, then fill the template.
+ * The default template is `[{issue}] {title}`.
+ */
+export function pullRequestTitle(input) {
+    const raw = input.title.trim();
+    if (!input.issue)
+        return raw;
+    const title = stripIssuePrefix(raw, input.issue);
+    const template = input.template?.trim() || DEFAULT_PR_TITLE;
+    return template.replaceAll("{issue}", input.issue).replaceAll("{title}", title).replace(/[ \t]{2,}/g, " ").trim();
+}
+/** Kebab-case title, at most 50 characters. An issue prefix is not part of the slug. */
+export function titleSlug(title, issue) {
+    const base = issue ? stripIssuePrefix(title, issue) : title.trim();
+    const slug = base
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const cut = slug.slice(0, 50).replace(/-+$/g, "");
+    return cut || "task";
+}
+/**
+ * The random suffix of a kiln job id (`j` + 14 digits + 4 hex), otherwise
+ * the last six alphanumeric characters.
+ */
+export function shortJobId(jobId) {
+    const hex = /^j\d{14}([0-9a-f]{4})$/.exec(jobId);
+    if (hex?.[1])
+        return hex[1];
+    const compact = jobId.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+    return compact.slice(-6) || "job";
+}
+export function defaultRemoteBranch(input) {
+    if (input.issue)
+        return formatBranchTemplate(DEFAULT_BRANCH_TEMPLATE, input);
+    const slug = titleSlug(input.title, input.issue);
+    return `kiln/${slug}-${shortJobId(input.jobId)}`;
+}
+export function formatBranchTemplate(template, input) {
+    const slug = titleSlug(input.title, input.issue);
+    return template
+        .replaceAll("{issue}", input.issue ?? "")
+        .replaceAll("{slug}", slug)
+        .replaceAll("{jobId}", input.jobId)
+        .replace(/\/{2,}/g, "/")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-\/]+|[-\/]+$/g, "");
+}
+export function isPublishableBranch(name) {
+    return (/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name) &&
+        !name.includes("..") &&
+        !name.includes("//") &&
+        !name.endsWith("/") &&
+        !name.endsWith(".lock") &&
+        !name.includes("@"));
+}
+/**
+ * Remote branch for this job. A name that already points at `localSha` is
+ * ours (a crash between push and the delivery record). Any other existing
+ * remote branch gets `-<short job id>` appended, or the full job id when
+ * the short id is already on the name.
+ */
+export function chooseRemoteBranch(input) {
+    if (input.recorded)
+        return input.recorded;
+    const desired = input.template ? formatBranchTemplate(input.template, input) : defaultRemoteBranch(input);
+    assertPublishable(desired);
+    const current = input.remoteSha(desired);
+    if (current === null || current === input.localSha)
+        return desired;
+    const short = shortJobId(input.jobId);
+    const already = desired.endsWith(`-${short}`) || desired.endsWith(`/${short}`);
+    const suffixed = (already ? `${desired}-${input.jobId}` : `${desired}-${short}`)
+        .replace(/[^A-Za-z0-9._/-]/g, "-")
+        .replace(/\/{2,}/g, "/")
+        .replace(/-{2,}/g, "-");
+    assertPublishable(suffixed);
+    const altSha = input.remoteSha(suffixed);
+    if (altSha === null || altSha === input.localSha)
+        return suffixed;
+    const full = `${desired}-${input.jobId}`.replace(/[^A-Za-z0-9._/-]/g, "-").replace(/-{2,}/g, "-");
+    assertPublishable(full);
+    return full;
+}
+function assertPublishable(name) {
+    if (isPublishableBranch(name))
+        return;
+    throw new Error(`Branch name ${JSON.stringify(name)} is not a safe git branch. Check the repo branch template.`);
+}

package/dist/reconcile.js

@@ -1,6 +1,9 @@
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
-/** Why a transient attempt failed. Written under `<kilnDir>/attempts`, not on the job. */
-export const FAILURE_REASONS = ["stalled", "orphaned", "crashed", "failed"];
+/**
+ * Why an attempt failed. Written under `<kilnDir>/attempts`, not on the job.
+ * `auth-failed` is not an automatic retry: the job stays in Needs human.
+ */
+export const FAILURE_REASONS = ["stalled", "orphaned", "crashed", "failed", "auth-failed"];
 export function inFlightCount(observation) {
     return observation.jobs.filter((job) => inFlight(job, observation)).length;
 }