@intentius/chant 0.124.30 → 0.124.31

package/dist/workspace/ci-run.js

@@ -22,7 +22,10 @@
  * own variables. The forge values a generated job reads from `${{ ... }}`
  * expressions or GitLab's predefined variables come from flags here:
  * `BASE_SHA` from `--base`, `PR_NUMBER` from `--pr`, and the commit from
- * `--commit`.
+ * `--commit`. The values a forge job gets from repository secrets come from
+ * the host's secrets file (`--secrets`, ./ci-secrets.ts, #4096), and every
+ * secret value is redacted from the run's events, record, copied report and
+ * output by the executor's `redact` option.
  *
  * The steps run in a fresh checkout of the commit: a detached `git worktree`
  * in a temporary directory outside the repository, removed when the run
@@ -37,23 +40,33 @@
  * key is given, so `chant ci tick --source runs` (#4044) judges the commit
  * from it. Its events are `kind: "pipeline"` and `runtime: "ci"`, and the
  * record and the events carry `runOrigin: { forge: "chant" }`.
+ *
+ * With a forge client (#4097) the job also sets a commit status at its
+ * commit: `pending` when it starts, `success` or `failure` when it settles.
+ * A status the forge refuses is a warning and never fails the job.
  */
 import { execFileSync } from "node:child_process";
-import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prLoopJobs, prLoopSetup, PR_LOOP_IMAGE } from "../components/pr-pipeline.js";
-import { detectForge, FORGE_KINDS } from "../pr-forge.js";
+import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS } from "../pr-forge.js";
+import { PR_APPLY_GATE } from "../pr-loop.js";
 import { formatError, formatWarning } from "../cli/format.js";
 import { pushLifecycleReport } from "../lifecycle/git.js";
 import { ACTIVITY_PROFILES } from "../op/activity-profiles.js";
 import { shellCmd } from "../op/activities/shell.js";
 import { OpRunFailure, runOpLocally } from "../op/local-executor.js";
+import { redactText } from "../op/redact.js";
 import { findWorkspaceRoot } from "../project-root.js";
+import { parseReportUrl, reportKey } from "../pr-report-url.js";
 import { ciTagSigner, RUNNER_KEY_ENV } from "./ci-green.js";
+import { ciRedactor, ciSecretsFor, CI_SECRETS_ENV, readCiSecrets } from "./ci-secrets.js";
+import { updateCiRunIndex } from "./ci-run-index.js";
 import { resolveMemberContext } from "./member-pipeline.js";
 import { signOpRunRecord } from "./trust/op-run-statement.js";
 import { gitTop } from "./tree.js";
+import { hostRunnerKey } from "./ci-runner-key.js";
 export const CI_JOB_NAMES = ["plan", "apply"];
 /** The Op each job is recorded as, which `ci.green` phases match. */
 export const CI_JOB_OPS = { plan: "pr-plan", apply: "pr-apply" };
@@ -89,19 +102,27 @@ export class CiRunError extends Error {
 }
 /**
  * The job's environment: the runner's base variables, the forge variables
- * and `passEnv` names it has, `CHANT_ENV` as a generated workflow sets it,
- * the commit as the forge spells it, and the job's own variables. A job
- * variable the forge fills from an expression comes from a flag, or from
- * the runner's environment for a token such as `GITHUB_TOKEN`; a literal
- * one, such as `CHANT_RUN_EVENTS_DIR`, is kept as it is.
+ * and `passEnv` names it has, the job's secrets from the host's secrets file
+ * (#4096), `CHANT_ENV` as a generated workflow sets it, the commit as the
+ * forge spells it, and the job's own variables. A job variable the forge
+ * fills from an expression comes from a flag, or from a secret or the
+ * runner's environment for a token such as `GITHUB_TOKEN`; a literal one,
+ * such as `CHANT_RUN_EVENTS_DIR`, is kept as it is. A secret replaces the
+ * runner's variable of the same name, and none replaces a variable the
+ * runner sets for the job. `CHANT_RUNNER_KEY` is never in it.
  */
 export function ciJobEnv(job, input) {
+    if (input.passEnv?.includes(RUNNER_KEY_ENV))
+        throw new CiRunError(`--pass-env names ${RUNNER_KEY_ENV}, and the runner key is never passed to a job`);
     const out = {};
     for (const name of [...CI_RUN_BASE_ENV, ...CI_RUN_FORGE_ENV, ...(input.passEnv ?? [])]) {
         const value = input.hostEnv[name];
         if (value !== undefined)
             out[name] = value;
     }
+    for (const [name, value] of Object.entries(input.secrets ?? {}))
+        if (name !== RUNNER_KEY_ENV)
+            out[name] = value;
     out.CHANT_ENV = input.env;
     out[input.forge === "gitlab" ? "CI_COMMIT_SHA" : "GITHUB_SHA"] = input.values.commit;
     const flags = {
@@ -118,10 +139,14 @@ export function ciJobEnv(job, input) {
         else if (!value.includes("$")) {
             out[name] = value;
         }
+        else if (input.secrets?.[name] !== undefined) {
+            out[name] = input.secrets[name];
+        }
         else if (input.hostEnv[name] !== undefined) {
             out[name] = input.hostEnv[name];
         }
     }
+    delete out[RUNNER_KEY_ENV];
     return out;
 }
 /** `line` with a `chant` at its start replaced by the command the caller names, when it names one. */
@@ -220,6 +245,67 @@ export function ciJobFailure(input) {
     }
     return { code: "command-failed", reason: firstLine(failed.error ?? "the command failed"), phase: failed.phase, ...exit };
 }
+/** A status description is cut to what GitHub and Forgejo keep. */
+const STATUS_DESCRIPTION = 140;
+const cut = (text, max = STATUS_DESCRIPTION) => (text.length > max ? `${text.slice(0, max - 3)}...` : text);
+/**
+ * A job's status context: `chant/pr-plan` for the plan, and for the apply
+ * `chant/<gate>`, which is `chant/pr-apply` unless `--gate` renamed the gate.
+ * pr-plan's own status is `chant/plan` (../pr-loop.ts), a different context.
+ */
+export function ciStatusContext(job, gate) {
+    return job === "apply" ? `chant/${gate ?? PR_APPLY_GATE}` : `chant/${CI_JOB_OPS.plan}`;
+}
+/**
+ * The link a job's status carries: the `--status-url` template with `{key}`
+ * filled, else the https `--report-url` followed by the key and a slash, else
+ * none (an `s3://` or `file://` URL is not one a browser opens).
+ */
+export function ciStatusUrl(input) {
+    const key = reportKey(input.pr ?? null, input.commit, input.member);
+    if (input.urlTemplate)
+        return input.urlTemplate.split("{key}").join(key);
+    const url = input.reportUrl?.trim();
+    if (url && /^https:\/\//.test(url))
+        return `${url.replace(/\/+$/, "")}/${key}/`;
+    return undefined;
+}
+/** What the settled status says: a short summary, or on failure the record's code and reason. */
+export function ciStatusSettled(op, result, seconds) {
+    if (result.status === "ok")
+        return { state: "success", description: cut(`${op} passed in ${seconds}s`) };
+    const why = result.record.failure;
+    const text = why ? `${why.code}: ${why.reason}` : result.failure ? `${result.failure.phase}: ${firstLine(result.failure.error)}` : `${op} failed`;
+    return { state: "failure", description: cut(text) };
+}
+/**
+ * The status client for `chant ci run` and `chant ci serve` (#4097), or none:
+ * off with `--no-status`, on GitLab (its client has no commit status call
+ * here), and without a forge token. A token with the rest of the forge's
+ * variables missing gives a warning instead.
+ */
+export function ciStatusFromEnv(input) {
+    if (input.noStatus || input.forge === "gitlab")
+        return {};
+    if (input.statusUrl !== undefined && !/^https?:\/\/\S+$/.test(input.statusUrl)) {
+        throw new CiRunError(`--status-url takes an http or https URL template such as https://host/reports/{key}, not ${JSON.stringify(input.statusUrl)}`);
+    }
+    const env = input.hostEnv;
+    const hasToken = Boolean(env.CHANT_FORGE_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN);
+    if (!hasToken)
+        return {};
+    try {
+        const client = forgeFromEnv(input.forge, env);
+        if (!client.setCommitStatus)
+            return {};
+        return { status: { client: { setCommitStatus: client.setCommitStatus.bind(client) }, ...(input.statusUrl ? { urlTemplate: input.statusUrl } : {}) } };
+    }
+    catch (err) {
+        if (err instanceof ForgeEnvironmentError)
+            return { warning: `no commit status will be set: ${err.message}` };
+        throw err;
+    }
+}
 const message = (err) => (err instanceof Error ? err.message : String(err));
 function git(cwd, args) {
     return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
@@ -275,6 +361,45 @@ function freshCheckout(top, commit) {
         },
     };
 }
+/**
+ * Add the settled job to the run index at its report URL (#4098). The pull
+ * request is the one the job's own report names, since a pr-apply finds it
+ * itself, else `--pr`. A warning, never a failure, when the index can't be
+ * updated.
+ */
+async function recordInIndex(input) {
+    const target = parseReportUrl(input.url);
+    if ("error" in target)
+        return input.warn(`the run index is not updated: ${target.error}`);
+    let pr = input.pr ?? null;
+    try {
+        const file = join(input.reportDir, `${CI_JOB_OPS[input.job]}.json`);
+        if (existsSync(file)) {
+            const said = JSON.parse(readFileSync(file, "utf-8")).pr;
+            if (Number.isInteger(said) && said > 0)
+                pr = said;
+        }
+    }
+    catch {
+        // The report is not readable; the flag stands.
+    }
+    const failure = input.record.failure;
+    const clean = (text) => (input.redact ? input.redact(text) : text);
+    const entry = {
+        job: input.job,
+        pr,
+        commit: input.commit,
+        status: input.record.status === "ok" ? "ok" : "fail",
+        ...(input.record.status !== "ok" ? { failure: { code: clean(failure?.code ?? "command-failed") } } : {}),
+        ...(input.member ? { member: clean(input.member) } : {}),
+        started: input.record.started,
+        ended: input.record.ended,
+        runId: clean(input.record.id),
+        key: clean(reportKey(pr, input.commit, input.member)),
+        runOrigin: CHANT_RUNNER_ORIGIN,
+    };
+    await updateCiRunIndex({ target, entry, ...(input.limit ? { limit: input.limit } : {}), warn: input.warn });
+}
 const ACTIVITIES = new Map([["shellCmd", shellCmd]]);
 /**
  * Run one pull-request job as a pipeline Op in a fresh checkout of the
@@ -293,7 +418,29 @@ export async function ciRun(req) {
     const job = jobs.find((j) => j.jobName === req.job);
     if (!job)
         throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
-    const jobEnv = ciJobEnv(job, { forge: req.forge, env: req.env, values: { base: req.base, pr: req.pr, commit }, hostEnv, passEnv: req.passEnv });
+    const jobEnv = ciJobEnv(job, {
+        forge: req.forge,
+        env: req.env,
+        values: { base: req.base, pr: req.pr, commit },
+        hostEnv,
+        passEnv: req.passEnv,
+        secrets: ciSecretsFor(req.secrets, req.job),
+    });
+    // #4096: the secrets and the job's secret-looking variables, redacted from everything the run writes and returns.
+    const redact = ciRedactor(jobEnv, req.secrets);
+    try {
+        const result = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
+        return redact ? { ...result, warnings: result.warnings.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
+    }
+    catch (err) {
+        if (redact && err instanceof Error)
+            err.message = redact(err.message);
+        throw err;
+    }
+}
+/** {@link ciRun} once the job and its environment are known. */
+async function runCiJob(req, at) {
+    const { cwd, top, commit, place, job, jobEnv, redact } = at;
     // The record is signed against .chant/trust.json at the commit the job runs, so a key that commit does not list is refused before anything runs.
     let signer;
     const early = [];
@@ -326,6 +473,22 @@ export async function ciRun(req) {
             mkdirSync(dirname(resume.job), { recursive: true });
             copyFileSync(resume.host, resume.job);
         }
+        const statusContext = ciStatusContext(req.job, req.loop?.gate);
+        const statusUrl = req.status
+            ? ciStatusUrl({ ...(req.status.urlTemplate ? { urlTemplate: req.status.urlTemplate } : {}), ...(req.loop?.reportUrl ? { reportUrl: req.loop.reportUrl } : {}), ...(req.pr !== undefined ? { pr: req.pr } : {}), commit, ...(place.member ? { member: place.member } : {}) })
+            : undefined;
+        const postStatus = async (state, description) => {
+            if (!req.status)
+                return;
+            try {
+                await req.status.client.setCommitStatus(commit, { context: statusContext, state, description: cut(redact ? redact(description) : description), ...(statusUrl ? { targetUrl: statusUrl } : {}) });
+            }
+            catch (err) {
+                warnings.push(`could not set the ${statusContext} status: ${message(err)}`);
+            }
+        };
+        const startedAt = Date.now();
+        await postStatus("pending", `${op.name} running`);
         let ledgerError;
         let result;
         try {
@@ -341,16 +504,22 @@ export async function ciRun(req) {
                 ...(req.stepOutput ? { stepOutput: req.stepOutput } : {}),
                 ...(signer ? { signRecord: (record) => signOpRunRecord(record, signer) } : {}),
                 onSignError: (err) => warnings.push(`the run was not signed: ${message(err)}`),
+                ...(redact ? { redact } : {}),
                 onLedgerError: (err) => {
                     ledgerError = `the job ran, and its record could not be written to chant/lifecycle: ${message(err)}`;
                 },
             });
         }
         catch (err) {
-            if (!(err instanceof OpRunFailure))
+            if (!(err instanceof OpRunFailure)) {
+                await postStatus("error", `${op.name} stopped: ${firstLine(message(err))}`);
                 throw err;
+            }
             result = err.result;
         }
+        const failedStep = result.records.find((r) => r.status === "fail");
+        const settled = ciStatusSettled(op.name, { status: result.status, record: result.record, ...(failedStep ? { failure: { phase: failedStep.phase, error: failedStep.error ?? "the step failed" } } : {}) }, Math.round((Date.now() - startedAt) / 1000));
+        await postStatus(settled.state, settled.description);
         if (resume && existsSync(resume.job)) {
             try {
                 mkdirSync(dirname(resume.host), { recursive: true });
@@ -365,6 +534,11 @@ export async function ciRun(req) {
         if (existsSync(written)) {
             report = resolve(cwd, req.output ?? PR_LOOP_REPORT_DIR);
             cpSync(written, report, { recursive: true });
+            if (redact)
+                redactTree(report, redact);
+        }
+        if (req.loop?.reportUrl) {
+            await recordInIndex({ url: req.loop.reportUrl, job: req.job, commit, member: place.member, pr: req.pr, record: result.record, reportDir: written, limit: req.runIndexLimit, ...(redact ? { redact } : {}), warn: (w) => warnings.push(w) });
         }
         if (ledgerError)
             throw new CiRunError(ledgerError);
@@ -387,6 +561,29 @@ export async function ciRun(req) {
         checkout.remove();
     }
 }
+/**
+ * Redact every text file under `dir` in place (#4096): the job's report, its
+ * change set and its component events, as `ci run` copied them out. A
+ * JSON file stays JSON. A file with a NUL byte is taken as binary and left.
+ */
+export function redactTree(dir, redact) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            redactTree(path, redact);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const bytes = readFileSync(path);
+        if (bytes.includes(0))
+            continue;
+        const text = bytes.toString("utf-8");
+        const clean = redactText(text, redact);
+        if (clean !== text)
+            writeFileSync(path, clean);
+    }
+}
 /** The text `chant ci run` prints when the run settles. */
 export function formatCiRun(r) {
     const lines = [`${r.op} ${r.status === "ok" ? "passed" : r.status === "fail" ? "failed" : r.status} at ${r.record.gitSha?.slice(0, 12) ?? "an unknown commit"}, run ${r.record.id} in ${r.record.env}`];
@@ -404,14 +601,34 @@ export function formatCiRun(r) {
 }
 // ── The command ──────────────────────────────────────────────────────────────
 const USAGE = "chant ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
-    "[--gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--image <image>] [--before-script <line>]... " +
-    "[--pr-build] [--pr-build-command <line>] " +
-    "[--chant <command>] [--pass-env <NAME>]... [--key <runner key.pem>] [-o <dir>]";
+    "[--gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
+    "[--pr-build] [--pr-build-command <line>] [--no-status] [--status-url <url template>] " +
+    "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The host's runner key in `--state`, or in ci serve's default state directory, when `--setup-key` made one there (#4099). */
+function hostRunnerKeyAt(cwd, statePath) {
+    const common = statePath ? null : (() => {
+        try {
+            return execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+        }
+        catch {
+            return null;
+        }
+    })();
+    const dir = statePath ? resolve(statePath) : common ? join(common, "chant", "ci-serve") : null;
+    return dir ? hostRunnerKey(dir) : undefined;
+}
+/** The secrets file `--secrets` names, else the one `CHANT_CI_SECRETS` names, read; undefined when neither names one (#4096). */
+export function ciSecretsOf(flag, env = process.env) {
+    const file = flag ?? (env[CI_SECRETS_ENV] || undefined);
+    return file === undefined ? undefined : readCiSecrets(resolve(file));
+}
 /** `chant ci run plan|apply` (#4094). */
 export async function runCiRun(ctx) {
     const { args } = ctx;
     try {
+        if (args.setupKey)
+            return (await import("./ci-serve.js")).runnerKeySetupCommand(ctx);
         const job = args.extraPositional;
         if (job !== "plan" && job !== "apply")
             throw new CiRunError(`ci run takes the job to run, plan or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
@@ -426,9 +643,17 @@ export async function runCiRun(ctx) {
             if (!ENV_NAME.test(name))
                 throw new CiRunError(`--pass-env takes a variable's name, not ${JSON.stringify(name)}`);
         const fromFlag = args.key !== undefined;
-        const runnerKey = fromFlag ? readFileSync(resolve(args.key), "utf-8") : process.env[RUNNER_KEY_ENV] || undefined;
+        // #4099: without --key or CHANT_RUNNER_KEY, the host's key that --setup-key made, if there is one. Like the variable, an unlisted one only warns.
+        const hostKey = fromFlag || process.env[RUNNER_KEY_ENV] ? undefined : hostRunnerKeyAt(process.cwd(), args.statePath);
+        const runnerKey = fromFlag ? readFileSync(resolve(args.key), "utf-8") : process.env[RUNNER_KEY_ENV] || hostKey?.pem;
+        const hostEnv = process.env;
+        const { status, warning } = ciStatusFromEnv({ forge: forge, hostEnv, noStatus: args.noStatus, statusUrl: args.statusUrl });
+        if (warning)
+            console.error(formatWarning({ message: warning }));
+        const secrets = ciSecretsOf(args.ciSecrets);
         const result = await ciRun({
             cwd: process.cwd(),
+            ...(status ? { status } : {}),
             job,
             env: args.env,
             forge: forge,
@@ -443,10 +668,12 @@ export async function runCiRun(ctx) {
                 ...(args.prBuild ? { build: true } : {}),
                 ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
             },
+            ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),
             ...(args.image ? { image: args.image } : {}),
             ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
             ...(args.ciChant ? { chant: args.ciChant } : {}),
             ...(args.passEnv?.length ? { passEnv: args.passEnv } : {}),
+            ...(secrets ? { secrets } : {}),
             ...(args.output ? { output: args.output } : {}),
             ...(runnerKey !== undefined ? { runnerKey, runnerKeyFromEnv: !fromFlag } : {}),
             ...(args.eventsJson ? { runEvents: (line) => void process.stdout.write(line) } : {}),

package/dist/workspace/ci-runner-key.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The runner key on a `chant ci serve` or `chant ci run` host (#4099, epic
+ * #4101).
+ *
+ * The host keeps its runner key in the serve's state directory, by default
+ * `<git common dir>/chant/ci-serve/runner-key.pem`: an Ed25519 private key in
+ * PEM, mode 0600, made by `--setup-key` when there is none. Its public half
+ * is the `ssh-ed25519` line `.chant/trust.json` lists under `runners`, and
+ * `--setup-key --trust` proposes that entry through `chant workspace trust
+ * runner add` (#3510) on a branch of its own, pushed for review. It never
+ * commits to the target branch: changing the trust config is a protected
+ * write, and the change is reviewed and merged like any other.
+ *
+ * `ci serve` refuses to start when its key is not listed, with the runner
+ * role, in `.chant/trust.json` at the target branch's head, since every run
+ * it signed would then be ignored by `ci tick --source runs`. `--unsigned`
+ * starts it without a key.
+ */
+/** The runner key's file in the state directory. */
+export declare const RUNNER_KEY_FILE = "runner-key.pem";
+/** The principal `--setup-key --trust` lists the key for when `--principal` names none. */
+export declare function defaultRunnerPrincipal(): string;
+export interface HostRunnerKey {
+    path: string;
+    pem: string;
+    /** `ssh-ed25519 <base64>`. */
+    publicKey: string;
+    /** Whether this call made it. */
+    created: boolean;
+}
+/** The host's runner key in `stateDir`, or undefined when there is none. */
+export declare function hostRunnerKey(stateDir: string): HostRunnerKey | undefined;
+/** The host's runner key in `stateDir`, made when there is none: Ed25519, PEM, mode 0600 in a directory of mode 0700. */
+export declare function ensureHostRunnerKey(stateDir: string): HostRunnerKey;
+/**
+ * The target branch's head, as the readers of runners take it: the remote's
+ * branch after a fetch (best effort), else the local branch. Undefined when
+ * neither exists.
+ */
+export declare function targetHead(top: string, branch: string, remote?: string): {
+    commit: string;
+    ref: string;
+} | undefined;
+/** The exact command that lists `publicKey` for `principal`. */
+export declare function trustCommand(principal: string, publicKey: string): string;
+/** Whether `.chant/trust.json` at `commit` lists the key as a runner holding the runner role: its principal, or why not. */
+export declare function runnerKeyListed(top: string, commit: string, pem: string): {
+    ok: true;
+    principal: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface RunnerTrustProposal {
+    /** The branch holding the commit, or null when the key was already listed at the target's head. */
+    branch: string | null;
+    commit: string | null;
+    /** Whether the branch was pushed to the remote. */
+    pushed: boolean;
+    /** The trust config's digest on the branch. */
+    digest: string | null;
+}
+/**
+ * Propose the runner entry for review (#4099): in a temporary worktree at
+ * the target's head, run `trust runner add` (#3510), commit the change on
+ * `chant/trust-runner/<principal>`, and push that branch to `remote` when
+ * the clone has it. The target branch is never written. The commit is made
+ * with the host's git identity and signing settings; when the policy at base
+ * has signers, the change needs a signature by a policy writer before it
+ * merges.
+ */
+export declare function proposeRunnerTrust(req: {
+    top: string;
+    branch: string;
+    principal: string;
+    publicKey: string;
+    by?: string;
+    remote?: string;
+}): RunnerTrustProposal;
+export interface RunnerKeySetup {
+    key: HostRunnerKey;
+    /** The target's head the trust config was read at, or null when there is no such branch. */
+    head: string | null;
+    /** The principal the key is listed for at the head, or null. */
+    listedAs: string | null;
+    principal: string;
+    command: string;
+    proposal?: RunnerTrustProposal;
+}
+/** `--setup-key [--trust]`: make or read the key, see whether the target's head lists it, and with `trust` propose the entry. */
+export declare function setupRunnerKey(req: {
+    top: string;
+    stateDir: string;
+    branch: string;
+    principal?: string;
+    trust?: boolean;
+    by?: string;
+}): RunnerKeySetup;
+/** What `--setup-key` prints on stderr; the public key alone goes to stdout. */
+export declare function formatRunnerKeySetup(s: RunnerKeySetup, branch: string): string;
+/**
+ * The key `ci serve` signs with, checked before its first poll (#4099): the
+ * `--key` file, else `CHANT_RUNNER_KEY`, else the host's key in the state
+ * directory. Throws, with the command that lists it, when there is none or
+ * `.chant/trust.json` at the target's head does not list it with the runner
+ * role. With `unsigned` there is no key and nothing is checked.
+ */
+export declare function ciServeRunnerKey(req: {
+    top: string;
+    stateDir: string;
+    branch: string;
+    keyFile?: string;
+    envKey?: string;
+    unsigned?: boolean;
+}): {
+    pem?: string;
+    fromFlag: boolean;
+    source: string;
+};
+//# sourceMappingURL=ci-runner-key.d.ts.map

package/dist/workspace/ci-runner-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-runner-key.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-runner-key.ts"],"names":[],"mappings":"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"}