c27019a · e847c64 · 7f25952 · 7b17d6b · 8c1648f
@@ -0,0 +1,13 @@
# Build pins
A writer marks a commit as a build worth keeping: an annotated tag at
`refs/builds/<label>` holding the commit, who pinned it, a note and an
optional `Parent:`/`Source:`. Git holds all of it; pinning runs no check and
wakes no agent. Ported from Jay Moran's developer-forge work ; `git/builds.ts`
is trimmed to what main calls).
- Page: `/<owner>/<name>/builds` lists pins; `/builds/new` is the form (Branches has a Pin button per branch and a Builds link); Preview serves a pinned commit (`build_preview`); Delete is behind `/-/confirm`.
- API: `GET/POST /api/v1/repos/:owner/:name/builds`, `PATCH`/`DELETE …/builds/:label` (rw scope, a person who writes; agents are refused).
- Terminal: on a repository, the palette's `<owner>/<name> — Builds` (`src/tui/screens/builds.ts`) lists the pins to anyone who may read it; a person who writes (never an agent) presses `p` to pin (prefilled with the next label and the default branch's tip), `n` to note, `d` to delete.
- Notes are an append-only list on `refs/forge/notes`. `FORGE_NOTES_INTENT=<file>` copies each person's note once into that file under `## Iterator notes`.
- Left out: demos and displays, screenshots, the Iterations graph, the lineage on Branches.
@@ -0,0 +1,141 @@
/**
      
        sentinelcrew
        11d ago
        
      
      pinBuild lets agents pin while the contract says a person who writes; notePin lets crew agents note while PATCH says agents are refused. Align code, contract and tests.
    
 * Pin a build: a writer marks one commit as a build worth keeping, under a
 * short label, with a note and where it came from. The pin is a git ref
 * (`git/builds.ts`), so it costs no check run and wakes no agent; the event
 * is what the feed and webhooks read.
 */
import type { App } from "../app.ts";
import { commitIdentity } from "../core/commit_identity.ts";
import { copyNoteToIntent } from "../core/intent_notes.ts";
import type { Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import {
  deletePin as gitDeletePin,
  pinBuild as gitPinBuild,
  noteFingerprint,
  notePinBuild,
  type BuildNote,
  type BuildPin,
  type DeletePinError,
  type PinBuildError,
  type SetNoteError,
} from "../git/builds.ts";
import { repoDir } from "../git/repos.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { requireWriter, type AccessError } from "./access.ts";
import { isMirror } from "../origins/write-through.ts";
export interface PinBuildInput {
  readonly label: string;
  readonly oid: string;
  readonly note?: string;
  readonly parent?: string | undefined;
  /** `pull #12`, `branch feat/x` or `commit`. */
  readonly source?: string;
}
export type PinBuildActionError = AccessError | PinBuildError | "mirrored";
/** A person who writes the repository, never an agent, and not on a mirror: who may pin, note or delete. */
function writerOf(app: App, actor: User | undefined, repo: Repo): Result<User, AccessError | "mirrored"> {
  const writer = requireWriter(app, actor, repo);
  if (!writer.ok) return writer;
  if (writer.value.kind === "agent") return err("forbidden");
  if (isMirror(app, repo)) return err("mirrored");
  return writer;
}
export async function pinBuild(
  app: App,
  actor: User | undefined,
  repo: Repo,
  input: PinBuildInput,
): Promise<Result<BuildPin, PinBuildActionError>> {
  // A person who writes, not an agent; a mirror's refs are its origin's.
  const writer = writerOf(app, actor, repo);
  if (!writer.ok) return writer;
  const who = commitIdentity(app.config, writer.value);
  const pinned = await gitPinBuild(repoDir(app.reposRoot, repo.ownerName, repo.name), {
    label: input.label.trim(),
    oid: input.oid.trim(),
    note: input.note ?? "",
    parent: input.parent === undefined || input.parent.trim() === "" ? undefined : input.parent.trim(),
    source: input.source ?? "commit",
    tagger: who,
  });
  if (!pinned.ok) return pinned;
  app.bus.append({
    kind: "build.pinned",
    repoId: repo.id,
    actorId: writer.value.id,
    payload: {
      label: pinned.value.label,
      oid: pinned.value.oid,
      parent: pinned.value.parent ?? null,
      source: pinned.value.source,
    },
  });
  return ok(pinned.value);
}
/**
 * Delete a pin: `refs/builds/<label>` with its cover and screenshots. A
 * person who writes the repository, never an agent. The commit and the
 * pin's notes stay.
 */
export async function deletePin(
  app: App,
  actor: User | undefined,
  repo: Repo,
  label: string,
): Promise<Result<{ readonly label: string; readonly oid: string }, AccessError | DeletePinError | "mirrored">> {
  const writer = writerOf(app, actor, repo);
  if (!writer.ok) return writer;
  const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
  const gone = await gitDeletePin(dir, label);
  if (!gone.ok) return gone;
  // Its notes stay: they are append-only (`git/builds.ts`).
  app.bus.append({
    kind: "build.deleted",
    repoId: repo.id,
    actorId: writer.value.id,
    payload: { label, oid: gone.value.oid, tag: gone.value.tag },
  });
  return ok({ label, oid: gone.value.oid });
}
/**
 * Add a note to a build: appended to `notes.json` on `refs/forge/notes`,
 * one commit by its author (`git/builds.ts`). `notes` is the note's text;
 * the older `note` and `body` join into it. A person who writes the
 * repository, never an agent (as the API contract says). The note is also copied, once, into the rolling intent doc when
 * the forge names one (`FORGE_NOTES_INTENT`, `core/intent_notes.ts`).
 */
export async function notePin(
  app: App,
  actor: User | undefined,
  repo: Repo,
  label: string,
  change: { readonly notes?: string | undefined; readonly note?: string | undefined; readonly body?: string | undefined },
): Promise<Result<{ readonly pin: BuildPin; readonly note: BuildNote }, AccessError | SetNoteError | "mirrored">> {
  const writer = writerOf(app, actor, repo);
  if (!writer.ok) return writer;
  const text = change.notes ?? [change.note, change.body].filter((s) => s !== undefined && s.trim() !== "").join("\n\n");
  const who = { name: writer.value.username, kind: "human" as const };
  const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
  const noted = await notePinBuild(dir, label, text, who, commitIdentity(app.config, writer.value));
  if (!noted.ok) return noted;
  const { pin, note, commit } = noted.value;
  app.bus.append({
    kind: "build.noted",
    repoId: repo.id,
    actorId: writer.value.id,
    payload: { label, oid: pin.oid, commit, note: noteFingerprint(note), by: note.kind },
  });
  if (note.kind === "human" && app.config.notesIntent !== undefined) {
    const copied = copyNoteToIntent(app.config.notesIntent, `${repo.ownerName}/${repo.name}`, note);
    if (!copied.ok) app.log.warn("note not copied to the intent doc", { file: app.config.notesIntent, error: copied.error });
  }
  return ok({ pin, note });
}
@@ -175,6 +175,11 @@
export interface ForgeConfig {
   * child). Printed verbatim wherever the forge says how to connect.
   */
  appSsh?: string;
  /**
   * The rolling intent doc a person's build note is copied into, once,
   * under "## Iterator notes" (`core/intent_notes.ts`). Unset copies none.
   */
  notesIntent?: string;
  /**
   * The repository holding this forge's own code, as `owner/name`
   * (`FORGE_REPO`, e.g. `trevato-apps/forge`). A spawned child forks it,
@@ -0,0 +1,16 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = {
  method: "delete",
  path: `${REPO}/builds/{label}`,
  summary: "Delete a pin: refs/builds/{label} with its cover and screenshots; the commit stays (rw scope, a person who writes); answers 204",
  auth: true,
  status: 204,
  refusals: {
    forbidden: "403: not a person who writes the repository (an agent is refused)",
    not_found: "404: no such repository or pin, or the caller cannot read it",
    mirrored: "409: the repository mirrors an origin",
    moved: "409: the pin changed while it was being deleted",
    git_failed: "422: git refused the change",
  },
};
@@ -0,0 +1,3 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = { method: "get", path: `${REPO}/builds`, summary: "List a repository's build pins (refs/builds/<label>), newest first; answers { items, next_cursor }", auth: false };
@@ -13,6 +13,7 @@
export { route as deleteApiV1ReposOwnerNameApp } from "./deleteApiV1ReposOwnerNa
export { route as deleteApiV1ReposOwnerNameAppDomainsHost } from "./deleteApiV1ReposOwnerNameAppDomainsHost.ts";
export { route as deleteApiV1ReposOwnerNameAppEnvVar } from "./deleteApiV1ReposOwnerNameAppEnvVar.ts";
export { route as deleteApiV1ReposOwnerNameBranchesBranch } from "./deleteApiV1ReposOwnerNameBranchesBranch.ts";
export { route as deleteApiV1ReposOwnerNameBuildsLabel } from "./deleteApiV1ReposOwnerNameBuildsLabel.ts";
export { route as deleteApiV1ReposOwnerNameCrewUsername } from "./deleteApiV1ReposOwnerNameCrewUsername.ts";
export { route as deleteApiV1ReposOwnerNameEgressGrants } from "./deleteApiV1ReposOwnerNameEgressGrants.ts";
export { route as deleteApiV1ReposOwnerNameHooksId } from "./deleteApiV1ReposOwnerNameHooksId.ts";
@@ -96,6 +97,7 @@
export { route as getApiV1ReposOwnerNameAppMembers } from "./getApiV1ReposOwnerN
export { route as getApiV1ReposOwnerNameAppNotes } from "./getApiV1ReposOwnerNameAppNotes.ts";
export { route as getApiV1ReposOwnerNameAppProductionOpen } from "./getApiV1ReposOwnerNameAppProductionOpen.ts";
export { route as getApiV1ReposOwnerNameBranches } from "./getApiV1ReposOwnerNameBranches.ts";
export { route as getApiV1ReposOwnerNameBuilds } from "./getApiV1ReposOwnerNameBuilds.ts";
export { route as getApiV1ReposOwnerNameCommits } from "./getApiV1ReposOwnerNameCommits.ts";
export { route as getApiV1ReposOwnerNameCommitsOid } from "./getApiV1ReposOwnerNameCommitsOid.ts";
export { route as getApiV1ReposOwnerNameCommitsOidCheck } from "./getApiV1ReposOwnerNameCommitsOidCheck.ts";
@@ -191,6 +193,7 @@
export { route as patchApiV1ConversationsId } from "./patchApiV1ConversationsId.
export { route as patchApiV1ForgeFollowing } from "./patchApiV1ForgeFollowing.ts";
export { route as patchApiV1ReposOwnerName } from "./patchApiV1ReposOwnerName.ts";
export { route as patchApiV1ReposOwnerNameApp } from "./patchApiV1ReposOwnerNameApp.ts";
export { route as patchApiV1ReposOwnerNameBuildsLabel } from "./patchApiV1ReposOwnerNameBuildsLabel.ts";
export { route as patchApiV1ReposOwnerNameIssuesNumber } from "./patchApiV1ReposOwnerNameIssuesNumber.ts";
export { route as patchApiV1ReposOwnerNameLabelsId } from "./patchApiV1ReposOwnerNameLabelsId.ts";
export { route as patchApiV1ReposOwnerNamePullsNumber } from "./patchApiV1ReposOwnerNamePullsNumber.ts";
@@ -248,6 +251,7 @@
export { route as postApiV1ReposOwnerNameAppNotesIdBan } from "./postApiV1ReposO
export { route as postApiV1ReposOwnerNameAppNotesIdHide } from "./postApiV1ReposOwnerNameAppNotesIdHide.ts";
export { route as postApiV1ReposOwnerNameAppNotesIdUnban } from "./postApiV1ReposOwnerNameAppNotesIdUnban.ts";
export { route as postApiV1ReposOwnerNameBranches } from "./postApiV1ReposOwnerNameBranches.ts";
export { route as postApiV1ReposOwnerNameBuilds } from "./postApiV1ReposOwnerNameBuilds.ts";
export { route as postApiV1ReposOwnerNameBuildsPreview } from "./postApiV1ReposOwnerNameBuildsPreview.ts";
export { route as postApiV1ReposOwnerNameChecksRecheck } from "./postApiV1ReposOwnerNameChecksRecheck.ts";
export { route as postApiV1ReposOwnerNameContents } from "./postApiV1ReposOwnerNameContents.ts";
@@ -0,0 +1,17 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = {
  method: "patch",
  path: `${REPO}/builds/{label}`,
  summary: "Edit a build's notes: `notes` is the whole text (markdown, at most 10 KB; its first line is the summary), written as `<label>.md` in one commit on `refs/forge/notes` by the editor; the tag is not rewritten. `note` (the first line) and `body` (the rest) are still taken for one release and joined into the file, a field left out staying (rw scope, a person who writes); answers the pin",
  auth: true,
  body: { notes: "string", note: "string", body: "string" },
  refusals: {
    forbidden: "403: not a person who writes the repository (an agent is refused)",
    not_found: "404: no such repository or pin, or the caller cannot read it",
    invalid_note: "422: the notes pass 10 KB, or `note` is not one line of at most 200 characters",
    mirrored: "409: the repository mirrors an origin",
    moved: "409: the pin changed while it was being edited",
    git_failed: "422: git refused the change",
  },
};
@@ -0,0 +1,11 @@
import { REPO, type Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: `${REPO}/builds`,
  summary: "Pin a commit as a build (rw scope, a writer's) at refs/builds/<label>; answers 201 with the pin",
  auth: true,
  body: { label: "string", sha: "string", note: "string", parent: "string", source: "string" },
  status: 201,
  refusals: { exists: "409: a pin with that label already exists" },
};
@@ -132,6 +132,9 @@
const READER_KINDS: ReadonlySet<string> = new Set([
  "account.removed",
  "branch.created",
  "branch.deleted",
  "build.pinned",
  "build.deleted",
  "build.noted",
  "invite.used",
  "user.updated",
  "user.key_added",
@@ -0,0 +1,58 @@
/**
      
        sentinelcrew
        11d ago
        
      
      The first line of a note is written unindented into the shared doc: a leading '#' or '-->' injects a heading or breaks the fingerprint comment. Neutralise it and test it.
    
 * A person's build note, copied verbatim and once into a rolling intent doc,
 * the way ui-iterator copies a round's notes (records/ui-iterator/notes.mjs,
 * `syncIntent`): one list line under "## Iterator notes", carrying a hidden
 * fingerprint so it is never copied twice. Agent notes are never copied:
 * intent holds people's words only. The doc must exist; none is created.
 */
import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { noteFingerprint, type BuildNote } from "../git/builds.ts";
import { err, ok, type Result } from "../kernel/result.ts";
const HEAD = "## Iterator notes";
/** A line of note text made inert in the doc: no comment can open or close, no heading start. */
export const inert = (line: string): string =>
  line.replace(/<!--/g, "<!- -").replace(/-->/g, "-- >").replace(/^(\s*)#/, "$1\\#");
/** The line `note` is copied as: `- <source> <iteration>, <by>, <date>: <first line> <!-- ui-iterator <fp> -->`, the rest indented. */
export function intentLine(source: string, note: BuildNote): string {
  const [first = "", ...rest] = note.text.split("\n").map(inert);
  const more = rest.map((l) => `  ${l}`).join("\n");
  return `- ${source} ${note.iteration}, ${note.by}, ${note.at.slice(0, 10)}: ${first} <!-- ui-iterator ${noteFingerprint(note)} -->${more ? `\n${more}` : ""}`;
}
/** `doc` with `line` appended at the end of its "## Iterator notes" section, made when missing. */
export function withIntentLine(doc: string, line: string): string {
  let text = doc;
  let at = text.indexOf(HEAD);
  if (at < 0) {
    text = text.replace(/\n*$/, `\n\n${HEAD}\n`);
    at = text.indexOf(HEAD);
  }
  // The section ends before the next heading, or at the end of the file.
  const next = text.slice(at + HEAD.length).search(/\n#{1,2} /);
  const cut = next < 0 ? text.length : at + HEAD.length + next;
  // Continue an existing list without a gap; start a new one after a blank line.
  const kept = text.slice(0, cut).replace(/\n*$/, "");
  const last = kept.slice(kept.lastIndexOf("\n") + 1);
  const before = kept + (last.startsWith("- ") || last.startsWith("  ") ? "\n" : "\n\n");
  return `${before}${line}\n${next < 0 ? "" : `\n${text.slice(cut).replace(/^\n*/, "")}`}`;
}
/** Copy `note` into the intent doc at `file`; answers whether it was written. */
export function copyNoteToIntent(file: string, source: string, note: BuildNote): Result<boolean, "no_doc" | "write_failed"> {
  if (note.kind !== "human") return ok(false);
  if (!existsSync(file)) return err("no_doc");
  try {
    const doc = readFileSync(file, "utf8");
    if (doc.includes(`<!-- ui-iterator ${noteFingerprint(note)} -->`)) return ok(false);
    const tmp = `${file}.forge-tmp`;
    writeFileSync(tmp, withIntentLine(doc, intentLine(source, note)));
    renameSync(tmp, file);
    return ok(true);
  } catch {
    return err("write_failed");
  }
}
@@ -0,0 +1,472 @@
/**
      
        sentinelcrew
        11d ago
        
      
      Much of this module has no caller (demos, covers, lineage helpers, readAllPinMessages citing a non-existent script). Trim to what is reachable.
    
 * Build pins: a person marks a commit as a build worth keeping. A pin is an
 * annotated tag object under `refs/builds/<label>` — the commit, who pinned
 * it and when, a note, and two trailers: `Parent:` (a label, when the
 * person named one) and `Source:` (the pull, branch or commit it came
 * from). Git holds all of it, so nothing here lives only in the database,
 * and pinning runs no check and wakes no agent. Notes live on
 * `refs/forge/notes` (see below).
 */
import { createHash } from "node:crypto";
import { readFileSync, statSync } from "node:fs";
import { join } from "node:path";
import { err, ok, type Result } from "../kernel/result.ts";
import { runGit, runGitCapture, runGitRaw } from "./env.ts";
import { isSafeOid, isSafeRef } from "./guard.ts";
export const BUILDS_PREFIX = "refs/builds/";
/** How many pins a lineage reads. A build list is for people to scan. */
export const PIN_LIMIT = 100;
export interface BuildPin {
  readonly label: string;
  /** The pinned commit. */
  readonly oid: string;
  readonly note: string;
  /** The pin the person named as this one's parent: `label` here, or
   * `owner/name:label` for a concept edge to another repository. */
  readonly parent: string | undefined;
  /** Where it was pinned from: `pull #12`, `branch feat/x` or `commit`. */
  readonly source: string;
  readonly pinnedBy: string;
  /** ISO time it was pinned. */
  readonly pinnedAt: string;
  /** Its notes, ranked, when it has any (`withNotes`); `note` is then the first one's text. */
  readonly notes?: readonly BuildNote[] | undefined;
  /** The tag message's note, when `note` holds the first of its notes instead. */
  readonly tagNote?: string | undefined;
}
/** A label is short and plain: letters, digits, `.`, `_` and `-`. */
export function isPinLabel(label: string): boolean {
  return (
    /^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(label) &&
    !label.endsWith(".lock") &&
    isSafeRef(`${BUILDS_PREFIX}${label}`)
  );
}
/**
 * What a pin may name as its parent: a label here, or `owner/name:label` in
 * another repository — a concept edge, for builds that share an idea but no
 * history.
 */
export function isPinParent(parent: string): boolean {
  const at = parent.lastIndexOf(":");
  if (at === -1) return isPinLabel(parent);
  const repo = parent.slice(0, at);
  return /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(repo) && isPinLabel(parent.slice(at + 1));
}
export type PinBuildError =
  | "invalid_label"
  | "invalid_parent"
  | "not_a_commit"
  | "exists"
  | "git_failed";
export interface PinInput {
  readonly label: string;
  readonly oid: string;
  readonly note: string;
  readonly parent?: string | undefined;
  readonly source: string;
  readonly tagger: { readonly name: string; readonly email: string };
  /** Seconds since the epoch; tests pass one to order pins. */
  readonly at?: number;
}
/** One line, no control bytes: what a trailer or tagger field may hold. */
const oneLine = (s: string): string =>
  s.replace(/[\x00-\x1f\x7f<>]/g, " ").trim();
/** Write the tag object and create the ref; an existing label is refused. */
export async function pinBuild(
  dir: string,
  input: PinInput,
): Promise<Result<BuildPin, PinBuildError>> {
  if (!isPinLabel(input.label)) return err("invalid_label");
  if (input.parent !== undefined && !isPinParent(input.parent))
    return err("invalid_parent");
  if (!isSafeOid(input.oid)) return err("not_a_commit");
  const kind = await runGitCapture(["cat-file", "-t", input.oid], { cwd: dir });
  if (kind.code !== 0 || kind.stdout.trim() !== "commit")
    return err("not_a_commit");
  const at = input.at ?? Math.floor(Date.now() / 1000);
  const note = input.note.replace(/\r/g, "").trim();
  const message = pinMessage(note === "" ? input.label : note, input.parent, oneLine(input.source) || "commit");
  const tag =
    `object ${input.oid}\ntype commit\ntag ${input.label}\n` +
    `tagger ${oneLine(input.tagger.name) || "forge"} <${oneLine(input.tagger.email)}> ${at} +0000\n\n` +
    message;
  const made = await runGit(["mktag"], { cwd: dir, stdin: tag });
  if (!made.ok) return err("git_failed");
  const created = await runGitCapture(
    ["update-ref", `${BUILDS_PREFIX}${input.label}`, made.value.trim(), ""],
    { cwd: dir },
  );
  if (created.code !== 0)
    return err(/already exists|reference already/i.test(created.stderr) ? "exists" : "git_failed");
  return ok({
    label: input.label,
    oid: input.oid,
    note,
    parent: input.parent,
    source: oneLine(input.source) || "commit",
    pinnedBy: oneLine(input.tagger.name) || "forge",
    pinnedAt: new Date(at * 1000).toISOString(),
  });
}
/** A pin's message: its note, then its trailers. */
function pinMessage(note: string, parent: string | undefined, source: string): string {
  const trailers = [...(parent === undefined ? [] : [`Parent: ${parent}`]), `Source: ${source}`];
  return `${note}\n\n${trailers.join("\n")}\n`;
}
const TRAILER = /^(Parent|Source): (.*)$/;
/** The trailers block at the end of a pin's message, and the note above it. */
function parsePinMessage(text: string): { note: string; parent: string | undefined; source: string } {
  const lines = text.replace(/\n+$/, "").split("\n");
  let parent: string | undefined;
  let source = "commit";
  let end = lines.length;
  while (end > 0) {
    const m = TRAILER.exec(lines[end - 1]!);
    if (m === null) break;
    if (m[1] === "Parent" && isPinParent(m[2]!)) parent = m[2]!;
    else if (m[1] === "Source") source = m[2]!;
    end--;
  }
  return { note: lines.slice(0, end).join("\n").trim(), parent, source };
}
/** The most bytes of one note's text. */
export const NOTES_MAX = 10 * 1024;
/** One note's text: plain text, not blank, that may break lines and tab. */
export const isNotes = (text: string): boolean =>
  text.trim() !== "" && new TextEncoder().encode(text).length <= NOTES_MAX && !/[\x00-\x08\x0b-\x1f\x7f]/.test(text);
export type SetNoteError = "invalid_note" | "not_found" | "moved" | "git_failed" | "notes_lost";
/**
 * A build's notes live on `refs/forge/notes` in its repository, in the
 * format ui-iterator keeps beside a round: `notes.json`, `{ "notes": [...] }`,
 * one entry per note. `iteration` is the pin's label (or a fork's or a
 * family's name, for a note on the whole line), `by` the author's name,
 * `kind` `human` or `agent`, `at` an ISO time, `text` plain text.
 *
 * Notes are append-only: a correction is a new note. `notes.lock` holds
 * every note's fingerprint, and an append refuses a `notes.json` that lost
 * one. Each append is one commit by its author. People's notes rank first.
 *
 */
export const NOTES_REF = "refs/forge/notes";
const NOTES_FILE = "notes.json";
const NOTES_LOCK = "notes.lock";
export const NOTE_KINDS = ["human", "agent"] as const;
export type NoteKind = (typeof NOTE_KINDS)[number];
/** One note, as `notes.json` holds it. */
export interface BuildNote {
  readonly iteration: string;
  readonly by: string;
  readonly kind: NoteKind;
  readonly at: string;
  readonly text: string;
}
/** A note's fingerprint, as ui-iterator's `notes.lock` keeps it: sha1 over its five fields, first 12 hex. */
export const noteFingerprint = (n: BuildNote): string =>
  createHash("sha1").update([n.iteration, n.by, n.kind, n.at, n.text].join("\u0000")).digest("hex").slice(0, 12);
/** People's notes first, then agents'; each oldest first. */
export const rankNotes = (notes: readonly BuildNote[]): BuildNote[] =>
  [...notes].sort((a, b) => (a.kind === b.kind ? Date.parse(a.at) - Date.parse(b.at) : a.kind === "human" ? -1 : 1));
function isBuildNote(n: unknown): n is BuildNote {
  if (typeof n !== "object" || n === null) return false;
  const o = n as Record<string, unknown>;
  return (
    typeof o["iteration"] === "string" &&
    typeof o["by"] === "string" &&
    (o["kind"] === "human" || o["kind"] === "agent") &&
    typeof o["at"] === "string" &&
    !Number.isNaN(Date.parse(o["at"])) &&
    typeof o["text"] === "string"
  );
}
/** `notes.json` as its notes, in file order; an entry that is not a note is skipped. */
function parseNotesJson(text: string): BuildNote[] {
  try {
    const data: unknown = JSON.parse(text);
    const list = Array.isArray(data) ? data : (data as { notes?: unknown } | null)?.notes;
    return Array.isArray(list)
      ? list.filter(isBuildNote).map((n) => ({ iteration: n.iteration, by: n.by, kind: n.kind, at: n.at, text: n.text }))
      : [];
  } catch {
    return [];
  }
}
/** `notes.lock` as its fingerprints. */
function parseLock(text: string): string[] {
  try {
    const data: unknown = JSON.parse(text);
    return Array.isArray(data) ? data.filter((h): h is string => typeof h === "string") : [];
  } catch {
    return [];
  }
}
/** Whether `dir` holds a notes ref, read without spawning git. */
export function holdsNotes(dir: string): boolean {
  try {
    if (statSync(join(dir, NOTES_REF)).isFile()) return true;
  } catch {
    // No loose ref.
  }
  try {
    return readFileSync(join(dir, "packed-refs"), "utf8").includes(` ${NOTES_REF}\n`);
  } catch {
    return false;
  }
}
/** The notes tree's entries at `tip`, raw (`ls-tree -z` lines), by file name. */
async function notesEntries(dir: string, tip: string): Promise<Map<string, { readonly line: string; readonly oid: string }> | undefined> {
  const listed = await runGitCapture(["ls-tree", "-z", tip], { cwd: dir });
  if (listed.code !== 0) return undefined;
  const out = new Map<string, { line: string; oid: string }>();
  for (const line of listed.stdout.split("\0")) {
    const m = /^(\d+) (\w+) ([0-9a-f]+)\t(.+)$/s.exec(line);
    if (m !== null) out.set(m[4]!, { line, oid: m[3]! });
  }
  return out;
}
/** Blobs' text by id, in one `cat-file --batch`. */
async function readBlobs(dir: string, oids: readonly string[]): Promise<Map<string, string>> {
  const out = new Map<string, string>();
  const safe = oids.filter(isSafeOid);
  if (safe.length === 0) return out;
  const read = await runGitRaw(["cat-file", "--batch"], { cwd: dir, stdin: `${safe.join("\n")}\n` });
  if (!read.ok) return out;
  const bytes = read.value;
  const text = new TextDecoder();
  let at = 0;
  while (at < bytes.length) {
    const nl = bytes.indexOf(0x0a, at);
    if (nl === -1) break;
    const [oid, kind, size] = text.decode(bytes.subarray(at, nl)).split(" ");
    if (kind !== "blob" || oid === undefined) {
      at = nl + 1;
      continue;
    }
    const n = Number(size);
    out.set(oid, text.decode(bytes.subarray(nl + 1, nl + 1 + n)));
    at = nl + 1 + n + 1;
  }
  return out;
}
/** The current tip of the notes ref, or undefined when there is none. */
async function notesTip(dir: string): Promise<string | undefined> {
  const at = await runGitCapture(["rev-parse", "--verify", "--quiet", `${NOTES_REF}^{commit}`], { cwd: dir });
  const oid = at.stdout.trim();
  return at.code === 0 && isSafeOid(oid) ? oid : undefined;
}
/** What the notes ref holds at `tip`: its tree, its notes and its lock. */
interface NotesState {
  readonly entries: Map<string, { readonly line: string; readonly oid: string }>;
  readonly notes: readonly BuildNote[];
  readonly lock: readonly string[];
}
async function readNotesState(dir: string, tip: string | undefined): Promise<NotesState | undefined> {
  if (tip === undefined) return { entries: new Map(), notes: [], lock: [] };
  const entries = await notesEntries(dir, tip);
  if (entries === undefined) return undefined;
  const file = entries.get(NOTES_FILE), lock = entries.get(NOTES_LOCK);
  const blobs = await readBlobs(dir, [
    ...(file === undefined ? [] : [file.oid]),
    ...(lock === undefined ? [] : [lock.oid]),
  ]);
  const notes = file === undefined ? [] : parseNotesJson(blobs.get(file.oid) ?? "");
  return { entries, notes, lock: lock === undefined ? [] : parseLock(blobs.get(lock.oid) ?? "") };
}
/** Each listed label's notes, ranked; a label with none is left out. */
export async function readBuildNotes(dir: string, labels: readonly string[]): Promise<Map<string, BuildNote[]>> {
  const out = new Map<string, BuildNote[]>();
  if (labels.length === 0 || !holdsNotes(dir)) return out;
  const tip = await notesTip(dir);
  if (tip === undefined) return out;
  const state = await readNotesState(dir, tip);
  if (state === undefined) return out;
  const wanted = new Set(labels);
  for (const n of state.notes) {
    if (!wanted.has(n.iteration)) continue;
    const list = out.get(n.iteration) ?? [];
    list.push(n);
    out.set(n.iteration, list);
  }
  for (const [label, list] of out) out.set(label, rankNotes(list));
  return out;
}
/** A pin with its notes: `note` becomes the first note's text, and the tag's own note moves to `tagNote`. */
export const withNotes = (pin: BuildPin, notes: readonly BuildNote[] | undefined): BuildPin =>
  notes === undefined || notes.length === 0 ? pin : { ...pin, note: notes[0]!.text, tagNote: pin.note, notes };
/** How many times an append retries when another write moved the notes ref first. */
const NOTES_TRIES = 8;
/**
 * Append `note` to `notes.json` on `refs/forge/notes`, with its fingerprint
 * in `notes.lock`: one commit by `author`, through plumbing, landed with a
 * lease on the tip it read. A `notes.json` missing a locked note is refused.
 */
export async function appendNote(
  dir: string,
  note: BuildNote,
  author: { readonly name: string; readonly email: string },
  message: string,
): Promise<Result<string, "moved" | "git_failed" | "notes_lost">> {
  const env = {
    GIT_AUTHOR_NAME: oneLine(author.name) || "forge",
    GIT_AUTHOR_EMAIL: oneLine(author.email),
    GIT_COMMITTER_NAME: oneLine(author.name) || "forge",
    GIT_COMMITTER_EMAIL: oneLine(author.email),
  };
  for (let attempt = 0; attempt < NOTES_TRIES; attempt++) {
    const tip = await notesTip(dir);
    const state = await readNotesState(dir, tip);
    if (state === undefined) return err("git_failed");
    const have = new Set(state.notes.map(noteFingerprint));
    if (state.lock.some((h) => !have.has(h))) return err("notes_lost");
    const notes = [...state.notes, note];
    const json = await runGit(["hash-object", "-w", "--stdin"], { cwd: dir, stdin: `${JSON.stringify({ notes }, null, 2)}\n` });
    const lock = await runGit(["hash-object", "-w", "--stdin"], {
      cwd: dir,
      stdin: `${JSON.stringify([...new Set(notes.map(noteFingerprint))].sort(), null, 1)}\n`,
    });
    if (!json.ok || !lock.ok) return err("git_failed");
    const drop = new Set([NOTES_FILE, NOTES_LOCK]);
    const lines = [...state.entries].filter(([name]) => !drop.has(name)).map(([, e]) => e.line);
    lines.push(`100644 blob ${json.value.trim()}\t${NOTES_FILE}`, `100644 blob ${lock.value.trim()}\t${NOTES_LOCK}`);
    const tree = await runGit(["mktree", "-z"], { cwd: dir, stdin: lines.map((l) => `${l}\0`).join("") });
    if (!tree.ok) return err("git_failed");
    const commit = await runGit(["commit-tree", tree.value.trim(), ...(tip === undefined ? [] : ["-p", tip]), "-m", message], { cwd: dir, env });
    if (!commit.ok) return err("git_failed");
    const oid = commit.value.trim();
    const moved = await runGitCapture(["update-ref", NOTES_REF, oid, tip ?? ""], { cwd: dir });
    if (moved.code === 0) return ok(oid);
  }
  return err("moved");
}
/**
 * Add a note to the pin `label`: `text` by `who`, now, appended to its
 * notes (`appendNote`). Answers the pin with its notes, the new note and
 * the commit. The tag stays.
 */
export async function notePinBuild(
  dir: string,
  label: string,
  text: string,
  who: { readonly name: string; readonly kind: NoteKind },
  author: { readonly name: string; readonly email: string },
): Promise<Result<{ readonly pin: BuildPin; readonly note: BuildNote; readonly commit: string }, SetNoteError>> {
  if (!isPinLabel(label)) return err("not_found");
  const clean = text.replace(/\r/g, "").trim();
  if (!isNotes(clean)) return err("invalid_note");
  const pin = await readTagPin(dir, label);
  if (pin === undefined) return err("not_found");
  const note: BuildNote = { iteration: label, by: who.name, kind: who.kind, at: new Date().toISOString(), text: clean };
  const written = await appendNote(dir, note, author, `Note on ${label}`);
  if (!written.ok) return written;
  const notes = (await readBuildNotes(dir, [label])).get(label) ?? [note];
  return ok({ pin: withNotes(pin, notes), note, commit: written.value });
}
export type DeletePinError = "not_found" | "moved" | "git_failed";
/**
 * Delete the pin `label`: `refs/builds/<label>`, only from the tag read
 * here, so a pin changed meanwhile is not deleted. The commit stays.
 */
export async function deletePin(dir: string, label: string): Promise<Result<{ readonly oid: string; readonly tag: string }, DeletePinError>> {
  if (!isPinLabel(label)) return err("not_found");
  const read = async (ref: string): Promise<string | undefined> => {
    const at = await runGitCapture(["rev-parse", "--verify", "--quiet", ref], { cwd: dir });
    const oid = at.stdout.trim();
    return at.code === 0 && isSafeOid(oid) ? oid : undefined;
  };
  const ref = `${BUILDS_PREFIX}${label}`;
  const tag = await read(ref);
  if (tag === undefined) return err("not_found");
  const commit = await runGitCapture(["rev-parse", "--verify", "--quiet", `${tag}^{commit}`], { cwd: dir });
  const lines = [`delete ${ref} ${tag}`];
  const done = await runGitCapture(["update-ref", "--stdin"], { cwd: dir, stdin: `start\n${lines.join("\n")}\nprepare\ncommit\n` });
  if (done.code !== 0) return err(/cannot lock|is at|expected/i.test(done.stderr) ? "moved" : "git_failed");
  return ok({ oid: commit.stdout.trim(), tag });
}
/** One pin by label with its tag message's note, its notes file not read. */
async function readTagPin(dir: string, label: string): Promise<BuildPin | undefined> {
  if (!isPinLabel(label)) return undefined;
  return (await listTagPins(dir, label))[0];
}
/**
 * Every pin, newest first, read in one `for-each-ref`; or the one `label`.
 * A pin's note is its notes file on `refs/forge/notes` when it has one,
 * else its tag message's.
 */
export async function listBuildPins(dir: string, label?: string): Promise<BuildPin[]> {
  const pins = await listTagPins(dir, label);
  const notes = await readBuildNotes(dir, pins.map((p) => p.label));
  if (notes.size === 0) return pins;
  return pins.map((p) => withNotes(p, notes.get(p.label)));
}
/** `listBuildPins` with each note as its tag message holds it. */
async function listTagPins(dir: string, label?: string): Promise<BuildPin[]> {
  const listed = await runGit(
    [
      "for-each-ref",
      "--sort=-taggerdate",
      `--count=${PIN_LIMIT}`,
      "--format=%(refname:strip=2)%00%(*objectname)%00%(*objecttype)%00%(taggername)%00%(taggerdate:iso-strict)%00%(contents)%00",
      label === undefined ? BUILDS_PREFIX.slice(0, -1) : `${BUILDS_PREFIX}${label}`,
    ],
    { cwd: dir },
  );
  if (!listed.ok || listed.value === "") return [];
  const fields = listed.value.split("\0");
  const pins: BuildPin[] = [];
  for (let i = 0; i + 5 < fields.length; i += 6) {
    const label = fields[i]!.replace(/^\n/, "");
    if (fields[i + 2] !== "commit" || !isPinLabel(label)) continue;
    const message = parsePinMessage(fields[i + 5]!);
    pins.push({
      label,
      oid: fields[i + 1]!,
      note: message.note,
      parent: message.parent,
      source: message.source,
      pinnedBy: fields[i + 3]!,
      pinnedAt: new Date(fields[i + 4]!).toISOString(),
    });
  }
  return pins;
}
@@ -343,6 +343,7 @@
import { FORGE_NOT_CARRIED } from "../origins/words.ts";
import { forgeOriginRoutes } from "./api/forge_origin.ts";
import { userRoutes } from "./api/user.ts";
import { appRoutes } from "./api/app.ts";
import { buildRoutes } from "./api/builds.ts";
import { appNoteRoutes } from "./api/app_notes.ts";
import { reportRoutes } from "./api/reports.ts";
import { rollbackRoutes } from "./api/rollback.ts";
@@ -3512,6 +3513,7 @@
export function apiRoutes(router: Router<Handler>): void {
  });
  appRoutes(router);
  buildRoutes(router);
  egressGrantRoutes(router);
@@ -0,0 +1,64 @@
/**
 * Build pins over the API: list, pin, add a note, delete
 * (`actions/builds.ts`, `git/builds.ts`). Reading is the repository's
 * readers'; every write needs the `rw` scope and a person who writes.
 */
import { deletePin, notePin, pinBuild } from "../../actions/builds.ts";
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import { listBuildPins } from "../../git/builds.ts";
import { repoDir } from "../../git/repos.ts";
import { loadRepo } from "../api.ts";
import type { Handler } from "../context.ts";
import { body, json, notFound, requireScope, respondAccess, str } from "../respond.ts";
import type { Router } from "../router.ts";
const STATUS: Record<string, number> = { exists: 409, mirrored: 409, moved: 409 };
export function buildRoutes(router: Router<Handler>): void {
  router.add("GET", "/api/v1/repos/:owner/:name/builds", async (ctx) => {
    notePhase(ctx.request, "session", takeSessionTime(ctx.request));
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    return json({ items: await listBuildPins(repoDir(ctx.app.reposRoot, repo.ownerName, repo.name)), next_cursor: null });
  });
  router.add("POST", "/api/v1/repos/:owner/:name/builds", async (ctx) => {
    const denied = requireScope(ctx, "rw");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const input = await body(ctx.request);
    const pinned = await pinBuild(ctx.app, ctx.auth.user, repo, {
      label: str(input.label),
      oid: str(input.sha),
      note: str(input.note),
      parent: str(input.parent),
      source: str(input.source) || "api",
    });
    return pinned.ok ? json(pinned.value, 201) : respondAccess(pinned.error, STATUS[pinned.error] ?? 422);
  });
  router.add("DELETE", "/api/v1/repos/:owner/:name/builds/:label", async (ctx) => {
    const denied = requireScope(ctx, "rw");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const done = await deletePin(ctx.app, ctx.auth.user, repo, ctx.params.label ?? "");
    return done.ok ? new Response(null, { status: 204 }) : respondAccess(done.error, STATUS[done.error] ?? 422);
  });
  router.add("PATCH", "/api/v1/repos/:owner/:name/builds/:label", async (ctx) => {
    const denied = requireScope(ctx, "rw");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const input = await body(ctx.request);
    const done = await notePin(ctx.app, ctx.auth.user, repo, ctx.params.label ?? "", {
      ...(typeof input.notes === "string" ? { notes: input.notes } : {}),
      ...(typeof input.note === "string" ? { note: input.note } : {}),
      ...(typeof input.body === "string" ? { body: input.body } : {}),
    });
    return done.ok ? json(done.value.pin) : respondAccess(done.error, STATUS[done.error] ?? 422);
  });
}
@@ -183,6 +183,7 @@
import {
  branchDelete,
  branchesPage,
} from "../web/pages/branches.ts";
import { buildsPage, deletePinSubmit, newBuildPage, pinBuildSubmit, previewBuildSubmit } from "../web/pages/builds.ts";
import { wavePage, wavesAtom, wavesPage } from "../web/pages/waves.ts";
import {
  contributeSubmit,
@@ -1255,6 +1256,12 @@
export function buildRouter(): Router<Handler> {
  // The repository's activity, for a feed reader.
  router.add("GET", "/:owner/:name/activity.atom", activityAtom);
  router.add("GET", "/:owner/:name/branches", branchesPage);
  // Build pins (`git/builds.ts`): the list, the form, and the writes behind them.
  router.add("GET", "/:owner/:name/builds", buildsPage);
  router.add("GET", "/:owner/:name/builds/new", newBuildPage);
  router.add("POST", "/:owner/:name/builds", pinBuildSubmit);
  router.add("POST", "/:owner/:name/builds/preview", previewBuildSubmit);
  router.add("POST", "/:owner/:name/builds/:label/delete", deletePinSubmit);
  router.add("GET", "/:owner/:name/waves.atom", wavesAtom);
  router.add("GET", "/:owner/:name/waves", wavesPage);
  router.add("GET", "/:owner/:name/waves/:version", wavePage);
@@ -251,6 +251,8 @@
const app = createApp({
  // The repository holding this forge's own code: a landing there is
  // checked out under releases/ and preflighted (#1662).
  ...releaseEnv(process.env),
  // FORGE_NOTES_INTENT: the intent doc people's build notes are copied into.
  ...((process.env.FORGE_NOTES_INTENT ?? "").trim() !== "" ? { notesIntent: (process.env.FORGE_NOTES_INTENT ?? "").trim() } : {}),
  // The one knob on the crew's bill: FORGE_CREW_CEILING_USD, dollars a day
  // across every repository. Unset is no forge-wide ceiling.
  ...(process.env.FORGE_MIGRATE_PRIVATE_HOSTS === "1"
@@ -0,0 +1,175 @@
/**
 * The Builds command, a repository's: its pinned builds, newest first, as
 * the builds page lists them (`listBuildPins`) — label, short commit, who
 * pinned it, when, and the first line of its note. Offered to, and read
 * for, only someone who may read the repository. A person who writes it
 * (never an agent) is also offered `p` pin, `n` note and `d` delete, each
 * through the page's own actions (`pinBuild`, `notePin`, `deletePin`),
 * which check again.
 */
import { deletePin, notePin, pinBuild } from "../../actions/builds.ts";
import { canRead, canWrite, type Repo } from "../../core/repos.ts";
import { listBuildPins, type BuildPin } from "../../git/builds.ts";
import { refTip } from "../../git/read.ts";
import { repoDir } from "../../git/repos.ts";
import { nextLabel } from "../../web/pages/builds.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import type { Command } from "../app/palette.ts";
import type { Session } from "../session.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import { ListState, ago, confirmScreen, metaOf, promptScreen } from "./common.ts";
export const NOT_FOUND_LINE = "No such repository";
export const NO_BUILDS_LINE = "No builds pinned yet.";
export const DELETED_LINE = "Deleted that pin; its commit and notes stay.";
/** What a refused or failed action reads as. */
const WORDS: Record<string, string> = {
  invalid_label: "A label is letters, digits, . _ and -, at most 40.",
  invalid_parent: "That parent is not a pin label.",
  not_a_commit: "That is not a commit in this repository.",
  exists: "That label is already pinned.",
  invalid_note: "A note is plain text, not blank, at most 10 KB.",
  not_found: "That pin is gone.",
  moved: "That pin changed meanwhile; try again.",
  mirrored: "A mirror's builds are its origin's.",
  notes_lost: "The notes ref lost a note; nothing was written.",
};
const say = (error: string): string => WORDS[error] ?? "Only a person who writes this repository can do that.";
/** Whether `f`'s person may pin, note or delete here: a writer who is not an agent. */
export const mayPin = (f: Session, repo: Repo): boolean =>
  f.user !== undefined && f.user.kind !== "agent" && canWrite(f.db, repo, f.user);
/** "label sha note…": the label, then the commit, then the rest as the note. */
export function parsePin(entry: string): { label: string; oid: string; note: string } | undefined {
  const [label = "", oid = "", ...rest] = entry.trim().split(/\s+/);
  return label === "" || oid === "" ? undefined : { label, oid, note: rest.join(" ") };
}
export function buildsScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const dir = repoDir(f.app.reposRoot, repo.ownerName, repo.name);
  let pins: BuildPin[] | undefined;
  let hidden = false;
  let note = "";
  const state = new ListState();
  const reload = async (): Promise<void> => {
    pins = await listBuildPins(dir);
    state.clamp(pins.length);
    ctx.invalidate();
  };
  const done = async (line: string): Promise<void> => {
    note = line;
    await reload();
  };
  const pin = async (): Promise<void> => {
    const tip = await refTip(dir, `refs/heads/${repo.defaultBranch}`);
    ctx.push(
      promptScreen(ctx, screen, {
        title: "Pin a build",
        label: "label, commit, then a note",
        value: `${nextLabel(pins ?? [])} ${tip ?? ""} `,
        onSubmit: (entry) => {
          const got = parsePin(entry);
          if (got === undefined) return "Give a label and a commit.";
          return ctx.track(
            pinBuild(f.app, f.user, repo, { ...got, source: "terminal" }).then((r) => done(r.ok ? `Pinned ${r.value.label}.` : say(r.error))),
          );
        },
      }),
    );
  };
  const addNote = (picked: BuildPin): void => {
    ctx.push(
      promptScreen(ctx, screen, {
        title: `Note on ${picked.label}`,
        label: "what you saw",
        onSubmit: (text) =>
          ctx.track(notePin(f.app, f.user, repo, picked.label, { notes: text }).then((r) => done(r.ok ? `Noted ${picked.label}.` : say(r.error)))),
      }),
    );
  };
  const ask = (picked: BuildPin): void => {
    ctx.push(
      confirmScreen(ctx, screen, {
        title: "Delete a pin",
        body: [`Delete the pin ${picked.label}? Its commit and notes stay.`],
        actions: [{ label: "Keep", variant: "ghost" }, { label: "Delete", variant: "danger" }],
        onChoose: (i) => {
          if (i < 1) return;
          void ctx.track(deletePin(f.app, f.user, repo, picked.label).then((r) => done(r.ok ? DELETED_LINE : say(r.error))));
        },
      }),
    );
  };
  const screen: Screen = {
    title: "Builds",
    // Read each time: someone who loses write access stops being offered the writes.
    get keys() {
      return [
        binding(["j", "k"], "move"),
        ...(mayPin(f, repo) ? [binding(["p"], "pin"), binding(["n"], "note"), binding(["d"], "delete")] : []),
        binding(["esc", "q"], "back"),
      ];
    },
    async load() {
      // Gated here as well as on the command: the screen is exported.
      hidden = !canRead(f.db, repo, f.user);
      if (hidden) pins = [];
      else await reload();
      ctx.invalidate();
    },
    render(area, s) {
      const c = ctx.theme.c;
      const right = area.x + area.w;
      const line = (y: number, text: string, fg = c.fg) => s.text(area.x + 1, area.y + y, truncate(text, area.w - 1), style(fg, c.bg), right);
      if (hidden) return void line(0, NOT_FOUND_LINE);
      if (pins === undefined) return void line(0, "Reading…");
      const rows = note === "" ? area.h : Math.max(1, area.h - 1);
      if (note !== "") line(area.h - 1, note, c.muted);
      if (pins.length === 0) return void line(0, NO_BUILDS_LINE);
      const from = state.window(rows, pins.length);
      for (let i = 0; i < rows; i++) {
        const p = pins[from + i];
        if (p === undefined) break;
        const picked = from + i === state.index;
        s.text(area.x, area.y + i, picked ? ">" : " ", style(c.accent, c.bg), right);
        const first = p.note.split("\n")[0] ?? "";
        line(i, `${p.label}  ${metaOf(p.oid.slice(0, 7), p.pinnedBy, ago(p.pinnedAt), first === p.label ? "" : first)}`, picked ? c.fg : c.muted);
      }
    },
    key(e) {
      note = "";
      const picked = pins?.[state.index];
      const write = !e.ctrl && !e.alt && !hidden && mayPin(f, repo);
      if (e.key === "j" || e.key === "down") state.move(1, pins?.length ?? 0);
      else if (e.key === "k" || e.key === "up") state.move(-1, pins?.length ?? 0);
      else if (e.key === "esc" || e.key === "q") ctx.pop();
      else if (e.key === "p" && write) void ctx.track(pin());
      else if (e.key === "n" && write && picked !== undefined) addNote(picked);
      else if (e.key === "d" && write && picked !== undefined) ask(picked);
      else return false;
      ctx.invalidate();
      return true;
    },
  };
  return screen;
}
/** The palette's door on a repository screen, for whoever may read it. */
export function buildsCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Command[] {
  if (repo === undefined || !canRead(f.db, repo, f.user)) return [];
  return [
    {
      id: "builds",
      title: `${repo.ownerName}/${repo.name} — Builds`,
      hint: "its pinned builds; a writer pins, notes and deletes",
      run: () => ctx.push(buildsScreen(f, ctx, repo)),
    },
  ];
}
@@ -133,6 +133,7 @@
import { makeItYoursScreen, yoursCommands } from "./yours.ts";
import { deleteRepoCommands } from "./deleterepo.ts";
import { grantsCommands } from "./grants.ts";
import { visionCommands } from "./vision.ts";
import { buildsCommands } from "./builds.ts";
import { labelsCommands } from "./labels.ts";
import { appEnvCommands } from "./appenv.ts";
import { autonomyCommands } from "./autonomy.ts";
@@ -1450,6 +1451,7 @@
export function workspaceScreen(
      ...hooksCommands(f, ctx, repo),
      ...visionCommands(f, ctx, repo),
      ...labelsCommands(f, ctx, repo),
      ...buildsCommands(f, ctx, repo),
      ...appEnvCommands(f, ctx, repo),
      ...autonomyCommands(f, ctx, repo),
    ],
@@ -210,6 +210,15 @@
function branchRow(
      </span>
      <span class="row-trail">
        ${divergence(row)}
        ${when(canWrite, () =>
          btn("Pin", {
            href: `${base}/builds/new?sha=${row.oid}&source=${encodeURIComponent(`branch ${row.name}`)}`,
            size: "sm",
            variant: "outline",
            icon: "pin",
            label: `Pin a build of ${row.name}`,
          }),
        )}
        ${when(!row.isDefault && canWrite, () =>
          btn("New pull", {
            href: `${base}/pulls/new?head=${encoded}`,
@@ -311,6 +320,7 @@
export async function renderBranches(
              head: html`<h2>
                  ${rows.length} branch${rows.length === 1 ? "" : "es"}
                </h2>
                ${when(scope.kind === "local", () => html`<span class="spacer"></span>${btn("Builds", { href: `${scope.base}/builds`, size: "sm", variant: "ghost", icon: "pin" })}`)}
                ${when(
                  !compared && scope.kind === "local",
                  () =>
@@ -0,0 +1,227 @@
/**
 * Builds: the pins people made (`git/builds.ts`), a short form to make one,
 * and "preview now" for any commit. A pin is a git ref, so pinning runs no
 * check and wakes no agent.
 */
import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
import { previewBuild } from "../../actions/build_preview.ts";
import { openEnvUrl } from "../../actions/apps.ts";
import { deletePin, pinBuild } from "../../actions/builds.ts";
import { canWrite } from "../../core/repos.ts";
import { exactRefOid } from "../../git/branches.ts";
import { listBuildPins, type BuildPin } from "../../git/builds.ts";
import { isSafeOid } from "../../git/guard.ts";
import { repoDir } from "../../git/repos.ts";
import type { Ctx } from "../../http/context.ts";
import { crumbsFor, loadRepo, notFoundPage, repoBase, repoHeader, repoPalette, signInFirst } from "../chrome.ts";
import { field as formValue, readForm } from "../form.ts";
import { html, when } from "../html.ts";
import { flashTo, page } from "../layout.ts";
import { btn, card, field, icon, sha, time } from "../ui.ts";
/** The newest label stepped on by one. */
export function nextLabel(pins: readonly BuildPin[]): string {
  const last = pins[0]?.label;
  if (last === undefined) return "v1";
  const letter = /^(.*\d)([a-y])$/.exec(last);
  if (letter) return `${letter[1]}${String.fromCharCode(letter[2]!.charCodeAt(0) + 1)}`;
  const num = /^(.*?)(\d+)$/.exec(last);
  if (num) return `${num[1]}${Number(num[2]) + 1}`;
  return `${last}-2`;
}
/** Renders a page and names `session` and `render` in Server-Timing. */
function timedPage(ctx: Ctx, opts: Parameters<typeof page>[0]): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  const started = performance.now();
  const response = page(opts);
  notePhase(ctx.request, "render", performance.now() - started);
  return response;
}
// GET /:owner/:name/builds — the pins, newest first.
export async function buildsPage(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  const base = repoBase(repo);
  const pins = await listBuildPins(repoDir(ctx.app.reposRoot, repo.ownerName, repo.name));
  const writer = ctx.auth.user !== undefined && canWrite(ctx.app.db, repo, ctx.auth.user);
  const body = html`${repoHeader(ctx, repo, "branches", { compact: true })}
    <div class="mt">
      ${card(
        pins.length === 0
          ? html`<p class="muted builds-none">No builds pinned yet.</p>`
          : html`<ul class="list">
              ${pins.map(
                (p) => html`<li>
                  <div class="row build-row">
                    <span class="row-lead">${icon("pin")}</span>
                    <span class="row-main">
                      <span class="row-title mono">${p.label}</span>
                      <span class="row-meta"
                        >${sha(p.oid, `${base}/commit/${p.oid}`)} · ${p.source} · pinned ${time(p.pinnedAt)} by
                        ${p.pinnedBy}${when(p.parent, (parent) => html` · under ${parent}`)}${when(
                          p.note,
                          (note) => html` · ${note}`,
                        )}</span
                      >
                    </span>
                    <span class="row-trail">
                      ${when(writer, () =>
                        html`<form method="post" action="${base}/builds/preview" class="build-preview">
                          <input type="hidden" name="sha" value="${p.oid}" />
                          ${btn("Preview", { type: "submit", size: "sm", variant: "outline", icon: "eye" })}
                        </form>`,
                      )}
                      ${when(writer, () =>
                        btn("Delete", {
                          href: `/-/confirm?to=${encodeURIComponent(`${base}/builds/${encodeURIComponent(p.label)}/delete`)}`,
                          size: "sm",
                          variant: "danger",
                          label: `Delete pin ${p.label}`,
                        }),
                      )}
                    </span>
                  </div>
                </li>`,
              )}
            </ul>`,
        {
          head: html`${icon("pin")}
            <h2>Builds</h2>
            ${when(writer, () => btn("Pin a build", { href: `${base}/builds/new`, size: "sm", variant: "primary" }))}`,
        },
      )}
    </div>`;
  return timedPage(ctx, { ctx, title: `Builds · ${repo.name}`, crumbs: crumbsFor(repo), palette: repoPalette(ctx, repo), body });
}
// GET /:owner/:name/builds/new?sha=&source= — the pin form.
export async function newBuildPage(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  if (!ctx.auth.user) return signInFirst(ctx);
  if (!canWrite(ctx.app.db, repo, ctx.auth.user)) return notFoundPage(ctx);
  const base = repoBase(repo);
  const dir = repoDir(ctx.app.reposRoot, repo.ownerName, repo.name);
  const pins = await listBuildPins(dir);
  const asked = ctx.url.searchParams.get("sha") ?? "";
  const want = isSafeOid(asked) ? asked : ((await exactRefOid(dir, `refs/heads/${repo.defaultBranch}`)) ?? "");
  const source = ctx.url.searchParams.get("source") ?? (isSafeOid(asked) ? "" : `branch ${repo.defaultBranch}`);
  const body = html`${repoHeader(ctx, repo, "branches", { compact: true })}
    <div class="mt">
      ${card(
        html`<form method="post" action="${base}/builds" class="stack">
          ${field({ label: "Commit", name: "sha", value: isSafeOid(want) ? want : "", required: true, mono: true, hint: "Full commit SHA." })}
          <input type="hidden" name="source" value="${source}" />
          ${field({ label: "Label", name: "label", value: nextLabel(pins), required: true, mono: true, hint: "Letters, digits, dot, dash or underscore. Example: v3." })}
          ${field({ label: "Note", name: "note", rows: 3, hint: "Optional." })}
          <div class="bar">
            ${btn("Pin build", { variant: "primary", icon: "pin" })}
            ${btn("Cancel", { href: `${base}/builds`, variant: "ghost" })}
          </div>
        </form>`,
        { head: html`${icon("pin")}<h2>Pin a build</h2>` },
      )}
    </div>`;
  return timedPage(ctx, { ctx, title: `Pin a build · ${repo.name}`, crumbs: crumbsFor(repo), palette: repoPalette(ctx, repo), body });
}
const PIN_ERRORS: Record<string, string> = {
  invalid_label: "Invalid label. Use letters, digits, dot, dash or underscore, up to 40 characters.",
  invalid_parent: "Parent is not a pin in this repository.",
  not_a_commit: "Commit not found in this repository.",
  exists: "A pin with that label already exists.",
  mirrored: "This repository is a mirror. Pin builds in a fork.",
  git_failed: "Pin failed: git refused the ref.",
};
const hidden = (error: string): boolean => error === "unauthorized" || error === "not_found" || error === "forbidden";
// POST /:owner/:name/builds — pin it.
export async function pinBuildSubmit(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  if (!ctx.auth.user) return signInFirst(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  const base = repoBase(repo);
  const pinned = await pinBuild(ctx.app, ctx.auth.user, repo, {
    label: formValue(form, "label"),
    oid: formValue(form, "sha"),
    note: formValue(form, "note"),
    parent: formValue(form, "parent"),
    source: formValue(form, "source") || "commit",
  });
  if (!pinned.ok) {
    if (hidden(pinned.error)) return notFoundPage(ctx);
    return flashTo(ctx, `${base}/builds/new?sha=${encodeURIComponent(formValue(form, "sha"))}`, {
      tone: "danger",
      message: PIN_ERRORS[pinned.error] ?? "Pin failed.",
    });
  }
  return flashTo(ctx, `${base}/builds`, {
    message: `Pinned ${pinned.value.label} at ${pinned.value.oid.slice(0, 7)}.`,
  });
}
// POST /:owner/:name/builds/:label/delete — behind /-/confirm.
export async function deletePinSubmit(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  if (!ctx.auth.user) return signInFirst(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  const gone = await deletePin(ctx.app, ctx.auth.user, repo, ctx.params.label ?? "");
  if (!gone.ok && hidden(gone.error)) return notFoundPage(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/builds`,
    gone.ok ? { message: `Deleted pin ${gone.value.label}.` } : { tone: "danger", message: "Delete failed." },
  );
}
const PREVIEW_ERRORS: Record<string, string> = {
  unverified: "Verify your email before previewing a build.",
  mirrored: "This repository is a mirror. Preview builds in a fork.",
  not_a_commit: "Commit not found in this repository.",
  no_runtime: "Apps are disabled on this forge.",
};
// POST /:owner/:name/builds/preview — serve one commit for a while, then open it.
export async function previewBuildSubmit(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  if (!ctx.auth.user) return signInFirst(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  const oid = formValue(form, "sha");
  const preview = await previewBuild(ctx.app, ctx.auth.user, repo, oid);
  if (!preview.ok) {
    if (hidden(preview.error)) return notFoundPage(ctx);
    return flashTo(ctx, `${repoBase(repo)}/builds`, {
      tone: "danger",
      message: PREVIEW_ERRORS[preview.error] ?? "Preview failed.",
    });
  }
  // Through the forge's own opener, so a private app's preview gets its grant.
  const opened = openEnvUrl(ctx.app, ctx.auth.user, repo, preview.value.env, "/");
  const url = opened.ok ? opened.value : preview.value.url;
  // Not a redirect: a form's redirect to another origin is held to the
  // page's CSP form-action. A script navigation is not; the proxy there
  // shows a page that refreshes itself until the build is up.
  return page({
    ctx,
    title: `Opening ${oid.slice(0, 7)} · ${repo.name}`,
    crumbs: crumbsFor(repo),
    scriptJs: `location.replace(${JSON.stringify(url).replace(/</g, "\\u003c")});`,
    body: html`<div class="mt">
      ${card(
        html`<p>Starting build <span class="mono">${oid.slice(0, 7)}</span>.</p>
          <p><a class="btn" data-variant="primary" href="${url}">Open ${url}</a></p>`,
        { head: html`${icon("eye")}<h2>Opening preview</h2>` },
      )}
    </div>`,
  });
}
@@ -0,0 +1,266 @@
/**
 * Build pins: a writer marks a commit under refs/builds/<label>; the
 * builds page lists them.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { notePin, pinBuild } from "../src/actions/builds.ts";
import { commitToBranch, createRepo } from "../src/actions/repos.ts";
import { getRepo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import { promote } from "./helpers/members.ts";
import { listBuildPins } from "../src/git/builds.ts";
import { repoDir } from "../src/git/repos.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { nextLabel } from "../src/web/pages/builds.ts";
describe("build pins", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let base: string;
  let alice: User;
  let bob: User;
  let aliceCookie: string;
  let bobCookie: string;
  const oids: Record<string, string> = {};
  const signIn = async (username: string) =>
    (
      (
        await fetch(`${base}/signin`, {
          method: "POST",
          body: new URLSearchParams({ username, password: "a-good-passphrase" }),
          redirect: "manual",
        })
      ).headers.get("set-cookie") ?? ""
    ).split(";")[0]!;
  const post = (path: string, cookie: string, body: Record<string, string>) =>
    fetch(`${base}${path}`, {
      method: "POST",
      headers: { cookie, origin: base },
      body: new URLSearchParams(body),
      redirect: "manual",
    });
  const fresh = () => getRepo(app.db, "alice", "game")!;
  const pins = () => listBuildPins(repoDir(app.reposRoot, "alice", "game"));
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-pins-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    base = servers.url;
    for (const name of ["alice", "bob"]) {
      const made = await createUser(app.db, { origin: "seed",
        trusted: true,
        username: name,
        email: `${name}@forge.local`,
        password: "a-good-passphrase",
        adminIfFirst: true,
      });
      if (!made.ok) throw new Error(made.error);
      if (name === "alice") alice = made.value;
      else bob = made.value;
    }
    promote(app.db, bob);
    aliceCookie = await signIn("alice");
    bobCookie = await signIn("bob");
    const made = await createRepo(app, alice, { name: "game", visibility: "public" });
    if (!made.ok) throw new Error(String(made.error));
    for (const [branch, message] of [
      ["main", "one"],
      ["main", "two"],
      ["idea", "idea a"],
      ["idea", "idea b"],
    ] as const) {
      const c = await commitToBranch(app, alice, fresh(), {
        branch,
        message,
        files: [{ path: `${message}.txt`, content: `${message}\n` }],
      });
      if (!c.ok) throw new Error(JSON.stringify(c.error));
      oids[message] = c.value.commitOid;
    }
  });
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("a writer pins a commit from the form; it is a ref with its note and source", async () => {
    const res = await post("/alice/game/builds", aliceCookie, {
      sha: oids.one!,
      label: "v1",
      note: "first playable",
      source: "branch main",
    });
    expect(res.status).toBe(303);
    expect(res.headers.get("location")).toBe("/alice/game/builds");
    const [pin] = await pins();
    expect(pin?.label).toBe("v1");
    expect(pin?.oid).toBe(oids.one!);
    expect(pin?.note).toBe("first playable");
    expect(pin?.source).toBe("branch main");
    expect(pin?.pinnedBy).toBe("alice");
  });
  test("a reader cannot pin, and a stranger's form is refused", async () => {
    const res = await post("/alice/game/builds", bobCookie, { sha: oids.two!, label: "evil" });
    expect(res.status).toBe(404);
    const forged = await fetch(`${base}/alice/game/builds`, {
      method: "POST",
      headers: { cookie: aliceCookie, origin: "https://evil.test" },
      body: new URLSearchParams({ sha: oids.two!, label: "evil" }),
      redirect: "manual",
    });
    expect(forged.status).toBe(403);
    expect((await pins()).map((p) => p.label)).not.toContain("evil");
  });
  test("bad labels, unknown commits and taken labels are refused", async () => {
    for (const label of ["-x", "a/b", "a b", "x".repeat(41), "refs..x"])
      expect(
        (await pinBuild(app, alice, fresh(), { label, oid: oids.two! })).ok,
      ).toBe(false);
    const missing = await pinBuild(app, alice, fresh(), { label: "ghost", oid: "f".repeat(40) });
    expect(missing.ok ? "" : missing.error).toBe("not_a_commit");
    const taken = await pinBuild(app, alice, fresh(), { label: "v1", oid: oids.two! });
    expect(taken.ok ? "" : taken.error).toBe("exists");
    const flag = await pinBuild(app, alice, fresh(), { label: "flag", oid: "--all" });
    expect(flag.ok).toBe(false);
  });
  test("the API lists the pins to a reader and refuses a write without a token", async () => {
    const listed = ((await (await fetch(`${base}/api/v1/repos/alice/game/builds`)).json()) as {
      items: { label: string }[];
    }).items;
    expect(listed.map((p) => p.label)).toContain("v1");
    const anon = await fetch(`${base}/api/v1/repos/alice/game/builds`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ label: "api1", sha: oids.two! }),
    });
    expect(anon.status).toBe(401);
    expect((await pins()).map((p) => p.label)).not.toContain("api1");
  });
  test("the offered label steps on from the newest", () => {
    const pin = (label: string) =>
      ({ label, oid: "", note: "", parent: undefined, source: "", pinnedBy: "", pinnedAt: "" }) as const;
    expect(nextLabel([])).toBe("v1");
    expect(nextLabel([pin("2a")])).toBe("2b");
    expect(nextLabel([pin("v3")])).toBe("v4");
    expect(nextLabel([pin("demo")])).toBe("demo-2");
  });
});
describe("build pins pages and notes", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let alice: User;
  let cookie: string;
  let oid: string;
  const post = (path: string, body: Record<string, string>, origin = servers.url) =>
    fetch(`${servers.url}${path}`, { method: "POST", headers: { cookie, origin }, body: new URLSearchParams(body), redirect: "manual" });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-pins2-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
    if (!made.ok) throw new Error(made.error);
    alice = made.value;
    const res = await fetch(`${servers.url}/signin`, { method: "POST", body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }), redirect: "manual" });
    cookie = (res.headers.get("set-cookie") ?? "").split(";")[0]!;
    const repo = await createRepo(app, alice, { name: "game", visibility: "public" });
    if (!repo.ok) throw new Error(String(repo.error));
    const c = await commitToBranch(app, alice, getRepo(app.db, "alice", "game")!, { branch: "main", message: "one", files: [{ path: "a.txt", content: "a\n" }] });
    if (!c.ok) throw new Error(JSON.stringify(c.error));
    oid = c.value.commitOid;
  });
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("the form is offered to a writer, the list shows the pin, the branches page links both", async () => {
    const form = await (await fetch(`${servers.url}/alice/game/builds/new?sha=${oid}`, { headers: { cookie } })).text();
    expect(form).toContain('name="label"');
    expect(form).toContain(`value="${oid}"`);
    expect(await (await fetch(`${servers.url}/alice/game/builds/new`)).text()).not.toContain('name="label"');
    expect((await post("/alice/game/builds", { sha: oid, label: "v1", note: "<b>first</b>" })).status).toBe(303);
    const list = await (await fetch(`${servers.url}/alice/game/builds`, { headers: { cookie } })).text();
    expect(list).toContain(">v1<");
    expect(list).toContain("&lt;b&gt;first&lt;/b&gt;");
    expect(list).not.toContain("<b>first</b>");
    const branches = await (await fetch(`${servers.url}/alice/game/branches`, { headers: { cookie } })).text();
    expect(branches).toContain("/alice/game/builds/new?sha=");
    expect(branches).toContain("/alice/game/builds");
  });
  test("a taken label is flashed back, not pinned twice", async () => {
    const again = await post("/alice/game/builds", { sha: oid, label: "v1" });
    expect(again.status).toBe(303);
    expect(again.headers.get("location")).toContain("/builds/new");
    expect((await listBuildPins(repoDir(app.reposRoot, "alice", "game"))).length).toBe(1);
  });
  test("a note is appended through the API, and copied once into the intent doc", async () => {
    const intent = join(dataDir, "intent.md");
    await Bun.write(intent, "# Intent\n");
    const noted = await notePin(
      { ...app, config: { ...app.config, notesIntent: intent } } as App,
      alice,
      getRepo(app.db, "alice", "game")!,
      "v1",
      { notes: "It plays." },
    );
    expect(noted.ok).toBe(true);
    const doc = await Bun.file(intent).text();
    expect(doc).toContain("## Iterator notes");
    expect(doc).toContain("It plays.");
    const pin = (await listBuildPins(repoDir(app.reposRoot, "alice", "game")))[0];
    expect(pin?.label).toBe("v1");
  });
  test("an agent cannot pin or note, even holding write access", async () => {
    const repo = getRepo(app.db, "alice", "game")!;
    const pins = () => listBuildPins(repoDir(app.reposRoot, "alice", "game"));
    const agent = { ...alice, kind: "agent" } as User;
    const pinned = await pinBuild(app, agent, repo, { label: "by-agent", oid: (await pins())[0]!.oid });
    expect(pinned).toEqual({ ok: false, error: "forbidden" });
    const noted = await notePin(app, agent, repo, (await pins())[0]!.label, { notes: "hi" });
    expect(noted).toEqual({ ok: false, error: "forbidden" });
  });
  test("a note cannot open a comment or a heading in the intent doc", async () => {
    const intent = join(dataDir, "intent-inject.md");
    await Bun.write(intent, "# Intent\n");
    const repo = getRepo(app.db, "alice", "game")!;
    const label = (await listBuildPins(repoDir(app.reposRoot, "alice", "game")))[0]!.label;
    const noted = await notePin({ ...app, config: { ...app.config, notesIntent: intent } } as App, alice, repo, label, {
      notes: "--> # Heading <!-- x\n# second\nmore",
    });
    expect(noted.ok).toBe(true);
    const doc = await Bun.file(intent).text();
    const line = doc.split("\n").find((l) => l.startsWith("- "))!;
    expect(line.match(/-->/g)?.length).toBe(1);
    expect(line.match(/<!--/g)?.length).toBe(1);
    expect(doc).not.toMatch(/^\s*#(?! Intent)(?!# Iterator notes)/m);
  });
  test("deleting a pin removes the ref and the list forgets it; a stranger's form is refused", async () => {
    expect((await post("/alice/game/builds/v1/delete", {}, "https://evil.test")).status).toBe(403);
    expect((await listBuildPins(repoDir(app.reposRoot, "alice", "game"))).length).toBe(1);
    expect((await post("/alice/game/builds/v1/delete", {})).status).toBe(303);
    expect(await listBuildPins(repoDir(app.reposRoot, "alice", "game"))).toEqual([]);
  });
});
@@ -0,0 +1,123 @@
/** The terminal's Builds screen: a repository's pins for its readers; pin, note and delete for a writer who is not an agent. */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pinBuild } from "../src/actions/builds.ts";
import { commitToBranch, createRepo } from "../src/actions/repos.ts";
import { createApp, type App } from "../src/app.ts";
import type { Repo } from "../src/core/repos.ts";
import { createUser, type User } from "../src/core/users.ts";
import { listBuildPins, readBuildNotes } from "../src/git/builds.ts";
import { refTip } from "../src/git/read.ts";
import { repoDir } from "../src/git/repos.ts";
import type { Ctx } from "../src/tui/app/app.ts";
import { createForgeApp, Session } from "../src/tui/forge.ts";
import { buildsCommands, buildsScreen, DELETED_LINE, NOT_FOUND_LINE, NO_BUILDS_LINE, parsePin } from "../src/tui/screens/builds.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
import { settleApp } from "./helpers/tui.ts";
quietLogs();
let dir: string;
let app: App;
let open: Repo;
let secret: Repo;
let alice: User;
let oid: string;
const guest = { sshUsername: "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test" };
const pins = (r: Repo) => listBuildPins(repoDir(app.reposRoot, r.ownerName, r.name));
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "forge-tui-builds-"));
  app = createApp({ dataDir: dir, port: 0 });
  const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
  if (!made.ok) throw new Error(made.error);
  alice = made.value;
  const mk = async (name: string, visibility: "public" | "private") => {
    const repo = await createRepo(app, alice, { name, visibility });
    if (!repo.ok) throw new Error(JSON.stringify(repo.error));
    const c = await commitToBranch(app, alice, repo.value, { branch: repo.value.defaultBranch, message: "start", files: [{ path: "README.md", content: "hi\n" }] });
    if (!c.ok) throw new Error(JSON.stringify(c.error));
    return repo.value;
  };
  open = await mk("game", "public");
  secret = await mk("secret", "private");
  oid = (await refTip(repoDir(app.reposRoot, "alice", "game"), `refs/heads/${open.defaultBranch}`))!;
  const s = await pinBuild(app, alice, secret, { label: "hidden-pin", oid: (await refTip(repoDir(app.reposRoot, "alice", "secret"), `refs/heads/${secret.defaultBranch}`))! });
  if (!s.ok) throw new Error(s.error);
}, 60_000);
afterAll(async () => {
  app.close();
  await rm(dir, { recursive: true, force: true });
});
const key = (key: string) => ({ type: "key" as const, key, ctrl: false, alt: false, shift: false });
async function drive(repo: Repo, user: User | undefined, steps: (string | string[])[] = []): Promise<string> {
  const terminal = headlessTerminal(100, 30);
  const { app: tui, session } = createForgeApp(app, user ? { ...guest, user } : guest, { terminal, exitHooks: false });
  tui.start();
  tui.ctx.push(buildsScreen(session, tui.ctx, repo));
  await settleApp(tui);
  for (const step of steps) {
    for (const k of Array.isArray(step) ? step : [step]) tui.dispatch(key(k));
    await settleApp(tui);
  }
  const text = tui.screen.toText();
  tui.stop?.();
  return text;
}
test("parsePin reads label, commit, then the note", () => {
  expect(parsePin(" v2  abc  it plays ")).toEqual({ label: "v2", oid: "abc", note: "it plays" });
  expect(parsePin("v2")).toBeUndefined();
});
test("a reader with no pins sees so, and a guest is offered no writes", async () => {
  const text = await drive(open, undefined, ["p"]);
  expect(text).toContain(NO_BUILDS_LINE);
  expect(text).not.toContain("Pin a build");
});
test("a writer pins from the prefilled prompt, notes it, and deletes it", async () => {
  // The prompt is prefilled with the next label and the default branch's tip; type a note and submit.
  let text = await drive(open, alice, ["p", [..."looks good"], "enter"]);
  expect(text).toContain("Pinned v1.");
  const [made] = await pins(open);
  expect(made).toMatchObject({ label: "v1", oid, source: "terminal", note: "looks good" });
  text = await drive(open, alice, ["n", [..."it plays"], "enter"]);
  expect(text).toContain("Noted v1.");
  const notes = await readBuildNotes(repoDir(app.reposRoot, "alice", "game"), ["v1"]);
  expect(notes.get("v1")?.[0]).toMatchObject({ by: "alice", kind: "human", text: "it plays" });
  text = await drive(open, alice, ["d", "right", "enter"]);
  expect(await pins(open)).toEqual([]);
  expect(text).toContain(DELETED_LINE);
});
test("an agent holding write access is offered no writes, and its keys do nothing", async () => {
  const p = await pinBuild(app, alice, open, { label: "keep", oid });
  expect(p.ok).toBe(true);
  const agent = { ...alice, kind: "agent" } as User;
  await drive(open, agent, ["d", "right", "enter"]);
  await drive(open, agent, ["p", "enter"]);
  expect((await pins(open)).map((x) => x.label)).toEqual(["keep"]);
});
test("a stranger opening a private repository's screen gets No such repository and no pin", async () => {
  const text = await drive(secret, undefined);
  expect(text).toContain(NOT_FOUND_LINE);
  expect(text).not.toContain("hidden-pin");
});
test("the command is offered to a reader and not for a repository the viewer cannot read", () => {
  const ctx = {} as Ctx;
  const stranger = new Session(app, guest);
  expect(buildsCommands(stranger, ctx, open).map((c) => c.id)).toEqual(["builds"]);
  expect(buildsCommands(stranger, ctx, secret)).toEqual([]);
  expect(buildsCommands(stranger, ctx, undefined)).toEqual([]);
});
		@@ -0,0 +1,13 @@
	1	# Build pins
	2
	3	A writer marks a commit as a build worth keeping: an annotated tag at
	4	`refs/builds/<label>` holding the commit, who pinned it, a note and an
	5	optional `Parent:`/`Source:`. Git holds all of it; pinning runs no check and
	6	wakes no agent. Ported from Jay Moran's developer-forge work ; `git/builds.ts`
	7	is trimmed to what main calls).
	8
	9	- Page: `/<owner>/<name>/builds` lists pins; `/builds/new` is the form (Branches has a Pin button per branch and a Builds link); Preview serves a pinned commit (`build_preview`); Delete is behind `/-/confirm`.
	10	- API: `GET/POST /api/v1/repos/:owner/:name/builds`, `PATCH`/`DELETE …/builds/:label` (rw scope, a person who writes; agents are refused).
	11	- Terminal: on a repository, the palette's `<owner>/<name> — Builds` (`src/tui/screens/builds.ts`) lists the pins to anyone who may read it; a person who writes (never an agent) presses `p` to pin (prefilled with the next label and the default branch's tip), `n` to note, `d` to delete.
	12	- Notes are an append-only list on `refs/forge/notes`. `FORGE_NOTES_INTENT=<file>` copies each person's note once into that file under `## Iterator notes`.
	13	- Left out: demos and displays, screenshots, the Iterations graph, the lineage on Branches.
		@@ -0,0 +1,141 @@
	1	/**
		sentinelcrew 11d ago pinBuild lets agents pin while the contract says a person who writes; notePin lets crew agents note while PATCH says agents are refused. Align code, contract and tests.
	2	* Pin a build: a writer marks one commit as a build worth keeping, under a
	3	* short label, with a note and where it came from. The pin is a git ref
	4	* (`git/builds.ts`), so it costs no check run and wakes no agent; the event
	5	* is what the feed and webhooks read.
	6	*/
	7
	8	import type { App } from "../app.ts";
	9	import { commitIdentity } from "../core/commit_identity.ts";
	10	import { copyNoteToIntent } from "../core/intent_notes.ts";
	11	import type { Repo } from "../core/repos.ts";
	12	import type { User } from "../core/users.ts";
	13	import {
	14	deletePin as gitDeletePin,
	15	pinBuild as gitPinBuild,
	16	noteFingerprint,
	17	notePinBuild,
	18	type BuildNote,
	19	type BuildPin,
	20	type DeletePinError,
	21	type PinBuildError,
	22	type SetNoteError,
	23	} from "../git/builds.ts";
	24	import { repoDir } from "../git/repos.ts";
	25	import { err, ok, type Result } from "../kernel/result.ts";
	26	import { requireWriter, type AccessError } from "./access.ts";
	27	import { isMirror } from "../origins/write-through.ts";
	28
	29	export interface PinBuildInput {
	30	readonly label: string;
	31	readonly oid: string;
	32	readonly note?: string;
	33	readonly parent?: string \| undefined;
	34	/** `pull #12`, `branch feat/x` or `commit`. */
	35	readonly source?: string;
	36	}
	37
	38	export type PinBuildActionError = AccessError \| PinBuildError \| "mirrored";
	39
	40	/** A person who writes the repository, never an agent, and not on a mirror: who may pin, note or delete. */
	41	function writerOf(app: App, actor: User \| undefined, repo: Repo): Result<User, AccessError \| "mirrored"> {
	42	const writer = requireWriter(app, actor, repo);
	43	if (!writer.ok) return writer;
	44	if (writer.value.kind === "agent") return err("forbidden");
	45	if (isMirror(app, repo)) return err("mirrored");
	46	return writer;
	47	}
	48
	49	export async function pinBuild(
	50	app: App,
	51	actor: User \| undefined,
	52	repo: Repo,
	53	input: PinBuildInput,
	54	): Promise<Result<BuildPin, PinBuildActionError>> {
	55	// A person who writes, not an agent; a mirror's refs are its origin's.
	56	const writer = writerOf(app, actor, repo);
	57	if (!writer.ok) return writer;
	58	const who = commitIdentity(app.config, writer.value);
	59	const pinned = await gitPinBuild(repoDir(app.reposRoot, repo.ownerName, repo.name), {
	60	label: input.label.trim(),
	61	oid: input.oid.trim(),
	62	note: input.note ?? "",
	63	parent: input.parent === undefined \|\| input.parent.trim() === "" ? undefined : input.parent.trim(),
	64	source: input.source ?? "commit",
	65	tagger: who,
	66	});
	67	if (!pinned.ok) return pinned;
	68	app.bus.append({
	69	kind: "build.pinned",
	70	repoId: repo.id,
	71	actorId: writer.value.id,
	72	payload: {
	73	label: pinned.value.label,
	74	oid: pinned.value.oid,
	75	parent: pinned.value.parent ?? null,
	76	source: pinned.value.source,
	77	},
	78	});
	79	return ok(pinned.value);
	80	}
	81
	82	/**
	83	* Delete a pin: `refs/builds/<label>` with its cover and screenshots. A
	84	* person who writes the repository, never an agent. The commit and the
	85	* pin's notes stay.
	86	*/
	87	export async function deletePin(
	88	app: App,
	89	actor: User \| undefined,
	90	repo: Repo,
	91	label: string,
	92	): Promise<Result<{ readonly label: string; readonly oid: string }, AccessError \| DeletePinError \| "mirrored">> {
	93	const writer = writerOf(app, actor, repo);
	94	if (!writer.ok) return writer;
	95	const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
	96	const gone = await gitDeletePin(dir, label);
	97	if (!gone.ok) return gone;
	98	// Its notes stay: they are append-only (`git/builds.ts`).
	99	app.bus.append({
	100	kind: "build.deleted",
	101	repoId: repo.id,
	102	actorId: writer.value.id,
	103	payload: { label, oid: gone.value.oid, tag: gone.value.tag },
	104	});
	105	return ok({ label, oid: gone.value.oid });
	106	}
	107
	108	/**
	109	* Add a note to a build: appended to `notes.json` on `refs/forge/notes`,
	110	* one commit by its author (`git/builds.ts`). `notes` is the note's text;
	111	* the older `note` and `body` join into it. A person who writes the
	112	* repository, never an agent (as the API contract says). The note is also copied, once, into the rolling intent doc when
	113	* the forge names one (`FORGE_NOTES_INTENT`, `core/intent_notes.ts`).
	114	*/
	115	export async function notePin(
	116	app: App,
	117	actor: User \| undefined,
	118	repo: Repo,
	119	label: string,
	120	change: { readonly notes?: string \| undefined; readonly note?: string \| undefined; readonly body?: string \| undefined },
	121	): Promise<Result<{ readonly pin: BuildPin; readonly note: BuildNote }, AccessError \| SetNoteError \| "mirrored">> {
	122	const writer = writerOf(app, actor, repo);
	123	if (!writer.ok) return writer;
	124	const text = change.notes ?? [change.note, change.body].filter((s) => s !== undefined && s.trim() !== "").join("\n\n");
	125	const who = { name: writer.value.username, kind: "human" as const };
	126	const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
	127	const noted = await notePinBuild(dir, label, text, who, commitIdentity(app.config, writer.value));
	128	if (!noted.ok) return noted;
	129	const { pin, note, commit } = noted.value;
	130	app.bus.append({
	131	kind: "build.noted",
	132	repoId: repo.id,
	133	actorId: writer.value.id,
	134	payload: { label, oid: pin.oid, commit, note: noteFingerprint(note), by: note.kind },
	135	});
	136	if (note.kind === "human" && app.config.notesIntent !== undefined) {
	137	const copied = copyNoteToIntent(app.config.notesIntent, `${repo.ownerName}/${repo.name}`, note);
	138	if (!copied.ok) app.log.warn("note not copied to the intent doc", { file: app.config.notesIntent, error: copied.error });
	139	}
	140	return ok({ pin, note });
	141	}
		@@ -175,6 +175,11 @@ export interface ForgeConfig {
175	175	* child). Printed verbatim wherever the forge says how to connect.
176	176	*/
177	177	appSsh?: string;
	178	/**
	179	* The rolling intent doc a person's build note is copied into, once,
	180	* under "## Iterator notes" (`core/intent_notes.ts`). Unset copies none.
	181	*/
	182	notesIntent?: string;
178	183	/**
179	184	* The repository holding this forge's own code, as `owner/name`
180	185	* (`FORGE_REPO`, e.g. `trevato-apps/forge`). A spawned child forks it,
		@@ -0,0 +1,16 @@
	1	import { REPO, type Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "delete",
	5	path: `${REPO}/builds/{label}`,
	6	summary: "Delete a pin: refs/builds/{label} with its cover and screenshots; the commit stays (rw scope, a person who writes); answers 204",
	7	auth: true,
	8	status: 204,
	9	refusals: {
	10	forbidden: "403: not a person who writes the repository (an agent is refused)",
	11	not_found: "404: no such repository or pin, or the caller cannot read it",
	12	mirrored: "409: the repository mirrors an origin",
	13	moved: "409: the pin changed while it was being deleted",
	14	git_failed: "422: git refused the change",
	15	},
	16	};
		@@ -0,0 +1,3 @@
	1	import { REPO, type Route } from "../shared.ts";
	2
	3	export const route: Route = { method: "get", path: `${REPO}/builds`, summary: "List a repository's build pins (refs/builds/<label>), newest first; answers { items, next_cursor }", auth: false };
		@@ -13,6 +13,7 @@ export { route as deleteApiV1ReposOwnerNameApp } from "./deleteApiV1ReposOwnerNa
13	13	export { route as deleteApiV1ReposOwnerNameAppDomainsHost } from "./deleteApiV1ReposOwnerNameAppDomainsHost.ts";
14	14	export { route as deleteApiV1ReposOwnerNameAppEnvVar } from "./deleteApiV1ReposOwnerNameAppEnvVar.ts";
15	15	export { route as deleteApiV1ReposOwnerNameBranchesBranch } from "./deleteApiV1ReposOwnerNameBranchesBranch.ts";
	16	export { route as deleteApiV1ReposOwnerNameBuildsLabel } from "./deleteApiV1ReposOwnerNameBuildsLabel.ts";
16	17	export { route as deleteApiV1ReposOwnerNameCrewUsername } from "./deleteApiV1ReposOwnerNameCrewUsername.ts";
17	18	export { route as deleteApiV1ReposOwnerNameEgressGrants } from "./deleteApiV1ReposOwnerNameEgressGrants.ts";
18	19	export { route as deleteApiV1ReposOwnerNameHooksId } from "./deleteApiV1ReposOwnerNameHooksId.ts";
		@@ -96,6 +97,7 @@ export { route as getApiV1ReposOwnerNameAppMembers } from "./getApiV1ReposOwnerN
96	97	export { route as getApiV1ReposOwnerNameAppNotes } from "./getApiV1ReposOwnerNameAppNotes.ts";
97	98	export { route as getApiV1ReposOwnerNameAppProductionOpen } from "./getApiV1ReposOwnerNameAppProductionOpen.ts";
98	99	export { route as getApiV1ReposOwnerNameBranches } from "./getApiV1ReposOwnerNameBranches.ts";
	100	export { route as getApiV1ReposOwnerNameBuilds } from "./getApiV1ReposOwnerNameBuilds.ts";
99	101	export { route as getApiV1ReposOwnerNameCommits } from "./getApiV1ReposOwnerNameCommits.ts";
100	102	export { route as getApiV1ReposOwnerNameCommitsOid } from "./getApiV1ReposOwnerNameCommitsOid.ts";
101	103	export { route as getApiV1ReposOwnerNameCommitsOidCheck } from "./getApiV1ReposOwnerNameCommitsOidCheck.ts";
		@@ -191,6 +193,7 @@ export { route as patchApiV1ConversationsId } from "./patchApiV1ConversationsId.
191	193	export { route as patchApiV1ForgeFollowing } from "./patchApiV1ForgeFollowing.ts";
192	194	export { route as patchApiV1ReposOwnerName } from "./patchApiV1ReposOwnerName.ts";
193	195	export { route as patchApiV1ReposOwnerNameApp } from "./patchApiV1ReposOwnerNameApp.ts";
	196	export { route as patchApiV1ReposOwnerNameBuildsLabel } from "./patchApiV1ReposOwnerNameBuildsLabel.ts";
194	197	export { route as patchApiV1ReposOwnerNameIssuesNumber } from "./patchApiV1ReposOwnerNameIssuesNumber.ts";
195	198	export { route as patchApiV1ReposOwnerNameLabelsId } from "./patchApiV1ReposOwnerNameLabelsId.ts";
196	199	export { route as patchApiV1ReposOwnerNamePullsNumber } from "./patchApiV1ReposOwnerNamePullsNumber.ts";
		@@ -248,6 +251,7 @@ export { route as postApiV1ReposOwnerNameAppNotesIdBan } from "./postApiV1ReposO
248	251	export { route as postApiV1ReposOwnerNameAppNotesIdHide } from "./postApiV1ReposOwnerNameAppNotesIdHide.ts";
249	252	export { route as postApiV1ReposOwnerNameAppNotesIdUnban } from "./postApiV1ReposOwnerNameAppNotesIdUnban.ts";
250	253	export { route as postApiV1ReposOwnerNameBranches } from "./postApiV1ReposOwnerNameBranches.ts";
	254	export { route as postApiV1ReposOwnerNameBuilds } from "./postApiV1ReposOwnerNameBuilds.ts";
251	255	export { route as postApiV1ReposOwnerNameBuildsPreview } from "./postApiV1ReposOwnerNameBuildsPreview.ts";
252	256	export { route as postApiV1ReposOwnerNameChecksRecheck } from "./postApiV1ReposOwnerNameChecksRecheck.ts";
253	257	export { route as postApiV1ReposOwnerNameContents } from "./postApiV1ReposOwnerNameContents.ts";
		@@ -0,0 +1,17 @@
	1	import { REPO, type Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "patch",
	5	path: `${REPO}/builds/{label}`,
	6	summary: "Edit a build's notes: `notes` is the whole text (markdown, at most 10 KB; its first line is the summary), written as `<label>.md` in one commit on `refs/forge/notes` by the editor; the tag is not rewritten. `note` (the first line) and `body` (the rest) are still taken for one release and joined into the file, a field left out staying (rw scope, a person who writes); answers the pin",
	7	auth: true,
	8	body: { notes: "string", note: "string", body: "string" },
	9	refusals: {
	10	forbidden: "403: not a person who writes the repository (an agent is refused)",
	11	not_found: "404: no such repository or pin, or the caller cannot read it",
	12	invalid_note: "422: the notes pass 10 KB, or `note` is not one line of at most 200 characters",
	13	mirrored: "409: the repository mirrors an origin",
	14	moved: "409: the pin changed while it was being edited",
	15	git_failed: "422: git refused the change",
	16	},
	17	};
		@@ -0,0 +1,11 @@
	1	import { REPO, type Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "post",
	5	path: `${REPO}/builds`,
	6	summary: "Pin a commit as a build (rw scope, a writer's) at refs/builds/<label>; answers 201 with the pin",
	7	auth: true,
	8	body: { label: "string", sha: "string", note: "string", parent: "string", source: "string" },
	9	status: 201,
	10	refusals: { exists: "409: a pin with that label already exists" },
	11	};
		@@ -132,6 +132,9 @@ const READER_KINDS: ReadonlySet<string> = new Set([
132	132	"account.removed",
133	133	"branch.created",
134	134	"branch.deleted",
	135	"build.pinned",
	136	"build.deleted",
	137	"build.noted",
135	138	"invite.used",
136	139	"user.updated",
137	140	"user.key_added",
		@@ -0,0 +1,58 @@
	1	/**
		sentinelcrew 11d ago The first line of a note is written unindented into the shared doc: a leading '#' or '-->' injects a heading or breaks the fingerprint comment. Neutralise it and test it.
	2	* A person's build note, copied verbatim and once into a rolling intent doc,
	3	* the way ui-iterator copies a round's notes (records/ui-iterator/notes.mjs,
	4	* `syncIntent`): one list line under "## Iterator notes", carrying a hidden
	5	* fingerprint so it is never copied twice. Agent notes are never copied:
	6	* intent holds people's words only. The doc must exist; none is created.
	7	*/
	8
	9	import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
	10	import { noteFingerprint, type BuildNote } from "../git/builds.ts";
	11	import { err, ok, type Result } from "../kernel/result.ts";
	12
	13	const HEAD = "## Iterator notes";
	14
	15	/** A line of note text made inert in the doc: no comment can open or close, no heading start. */
	16	export const inert = (line: string): string =>
	17	line.replace(/<!--/g, "<!- -").replace(/-->/g, "-- >").replace(/^(\s*)#/, "$1\\#");
	18
	19	/** The line `note` is copied as: `- <source> <iteration>, <by>, <date>: <first line> <!-- ui-iterator <fp> -->`, the rest indented. */
	20	export function intentLine(source: string, note: BuildNote): string {
	21	const [first = "", ...rest] = note.text.split("\n").map(inert);
	22	const more = rest.map((l) => ` ${l}`).join("\n");
	23	return `- ${source} ${note.iteration}, ${note.by}, ${note.at.slice(0, 10)}: ${first} <!-- ui-iterator ${noteFingerprint(note)} -->${more ? `\n${more}` : ""}`;
	24	}
	25
	26	/** `doc` with `line` appended at the end of its "## Iterator notes" section, made when missing. */
	27	export function withIntentLine(doc: string, line: string): string {
	28	let text = doc;
	29	let at = text.indexOf(HEAD);
	30	if (at < 0) {
	31	text = text.replace(/\n*$/, `\n\n${HEAD}\n`);
	32	at = text.indexOf(HEAD);
	33	}
	34	// The section ends before the next heading, or at the end of the file.
	35	const next = text.slice(at + HEAD.length).search(/\n#{1,2} /);
	36	const cut = next < 0 ? text.length : at + HEAD.length + next;
	37	// Continue an existing list without a gap; start a new one after a blank line.
	38	const kept = text.slice(0, cut).replace(/\n*$/, "");
	39	const last = kept.slice(kept.lastIndexOf("\n") + 1);
	40	const before = kept + (last.startsWith("- ") \|\| last.startsWith(" ") ? "\n" : "\n\n");
	41	return `${before}${line}\n${next < 0 ? "" : `\n${text.slice(cut).replace(/^\n*/, "")}`}`;
	42	}
	43
	44	/** Copy `note` into the intent doc at `file`; answers whether it was written. */
	45	export function copyNoteToIntent(file: string, source: string, note: BuildNote): Result<boolean, "no_doc" \| "write_failed"> {
	46	if (note.kind !== "human") return ok(false);
	47	if (!existsSync(file)) return err("no_doc");
	48	try {
	49	const doc = readFileSync(file, "utf8");
	50	if (doc.includes(`<!-- ui-iterator ${noteFingerprint(note)} -->`)) return ok(false);
	51	const tmp = `${file}.forge-tmp`;
	52	writeFileSync(tmp, withIntentLine(doc, intentLine(source, note)));
	53	renameSync(tmp, file);
	54	return ok(true);
	55	} catch {
	56	return err("write_failed");
	57	}
	58	}