@intentius/chant 0.124.29 → 0.124.31

package/dist/workspace/ci-serve.d.ts

@@ -0,0 +1,227 @@
+/**
+ * `chant ci serve` (#4095, epic #4101): the chant runner's trigger loop on one
+ * host. It polls the forge for the open pull requests into the target branch
+ * and for the branch's head, and runs the pull-request jobs with
+ * {@link ciRun} (./ci-run.ts): `plan` for each new pull request head, and
+ * `apply` for each new commit on the target branch, measured from the head
+ * the previous poll saw (the push's `before`).
+ *
+ * - Dedupe. A state file in the state directory keeps every job it started,
+ *   keyed by job and commit (`plan:<pr>:<sha>`, `apply:<sha>`), with how it
+ *   ended, and the target head the last apply was measured to. A job already
+ *   in it is not started again, unless it failed and `rerunFailed` asks for
+ *   it: the forge's "re-run failed jobs".
+ * - One apply per group. An apply takes the git-ref lease (../lifecycle/lease.ts,
+ *   the one `chant operator` holds) named for `prApplyGroup`, renews it while
+ *   it runs and releases it after. An apply that finds it held waits for a
+ *   later poll, as a forge's concurrency group queues it.
+ * - Merged pull request. An apply asks the forge for the pull request whose
+ *   merge commit the new head is (`pullRequestFor`, as pr-apply does) and
+ *   passes it as `--pr`, so its commit status link and run index use
+ *   `<pr>/<commit>`. With none found it runs without `--pr`.
+ * - Resume records. Each apply gets `<state>/resume/<prApplyRecordKey>.json`
+ *   as its `--resume` record, so a re-run of a failed apply at the same
+ *   commit finishes under the approval it has. This replaces the forge's CI
+ *   cache.
+ * - Capacity. At most `maxJobs` jobs run at once. A job over the limit is not
+ *   recorded, so a later poll starts it.
+ *
+ * Host mode only: each job runs in a fresh worktree on this host as this
+ * user, with the clean environment `ciRun` gives it. A pull request from a
+ * fork is never planned, and with `authors` only those people's pull requests
+ * are. Container isolation is #4015.
+ *
+ * A webhook is not here yet. {@link ciServeSchedule} takes triggers, and
+ * {@link ciServeObserve} is the poll that makes them; a webhook handler would
+ * turn a checked payload into the same triggers and schedule them.
+ */
+import { type OpenPullRequest } from "../pr-forge.js";
+import type { CommandContext } from "../cli/registry.js";
+import { type CiJobName, type CiRunRequest, type CiRunResult } from "./ci-run.js";
+/** The forges `ci serve` polls. GitLab is later. */
+export type CiServeForgeKind = "github" | "forgejo";
+/** What `ci serve` reads from the forge: the two calls GitHub's and Forgejo's clients have (../pr-forge.ts). */
+export interface CiServeForge {
+    openPullRequests(base: string): Promise<OpenPullRequest[]>;
+    branchHead(branch: string): Promise<string | undefined>;
+    /** The merged pull request that produced a commit, as pr-apply finds it (`pullRequestFor`). Without it an apply gets no `--pr`. */
+    pullRequestFor?(sha: string): Promise<number | null>;
+}
+/** A job the forge's state calls for: the plan of a pull request's head, or the apply of a target-branch commit. */
+export type CiServeTrigger = {
+    job: "plan";
+    commit: string;
+    base: string;
+    pr: number;
+    rerun?: boolean;
+} | {
+    job: "apply";
+    commit: string;
+    base: string;
+    rerun?: boolean;
+};
+/** One job in the state file. */
+export interface CiServeJobState {
+    job: CiJobName;
+    commit: string;
+    base: string;
+    pr?: number;
+    /** `running` while it runs; a `running` entry no live process holds is taken as failed. */
+    status: "running" | "ok" | "fail";
+    runId: string;
+    attempts: number;
+    startedAt: string;
+    settledAt?: string;
+    /** Why it failed, in a line. */
+    failure?: string;
+    /** Where its report was copied. */
+    report?: string;
+}
+/** The state file, `<state>/<prApplyGroup>.json`. */
+export interface CiServeState {
+    schema: 1;
+    forge: CiServeForgeKind;
+    repo: string;
+    env: string;
+    branch: string;
+    member?: string;
+    /** The target branch's head the last apply was measured to, or the head the first poll found. */
+    target?: string;
+    jobs: Record<string, CiServeJobState>;
+}
+/** What a pass did, in order, for the log. */
+export type CiServeEvent = {
+    type: "baseline";
+    commit: string;
+} | {
+    type: "no-branch";
+    branch: string;
+} | {
+    type: "skipped";
+    pr: number;
+    reason: "fork" | "author";
+    author?: string;
+} | {
+    type: "held";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    reason: "capacity" | "lease";
+    heldBy?: string;
+} | {
+    type: "started";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    base: string;
+    runId: string;
+    attempt: number;
+    resume?: string;
+} | {
+    type: "settled";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    status: "ok" | "fail";
+    failure?: string;
+    report?: string;
+} | {
+    type: "error";
+    message: string;
+};
+/** The `ciRun` request fields `ci serve` passes through to every job: the generator's options and the runner's. */
+export type CiServeJobOptions = Omit<CiRunRequest, "cwd" | "job" | "env" | "forge" | "base" | "pr" | "commit" | "output" | "resumeRecord" | "runId">;
+export interface CiServeOptions {
+    /** The host's clone, or a workspace member's directory in it. */
+    cwd: string;
+    forge: CiServeForgeKind;
+    /** `owner/name`. */
+    repo: string;
+    env: string;
+    client: CiServeForge;
+    /** Default `<git common dir>/chant/ci-serve`. */
+    stateDir?: string;
+    /** Default 1. */
+    maxJobs?: number;
+    /** Plan only pull requests these logins opened, without case. Default anyone with a branch in the repository. */
+    authors?: readonly string[];
+    /** Run again the failed apply at the target's head, and the failed plans of open heads. */
+    rerunFailed?: boolean;
+    /** Passed to each job. `job.hostEnv` gets `GITHUB_REPOSITORY` set to `repo`. */
+    job?: CiServeJobOptions;
+    /** This process's lease identity. Default `currentHolderId()`. */
+    holder?: string;
+    leaseTtlMs?: number;
+    log?: (event: CiServeEvent) => void;
+    now?: () => Date;
+    /** Runs a job. Default {@link ciRun}. */
+    run?: (req: CiRunRequest) => Promise<CiRunResult>;
+}
+/** The jobs this process runs now, by state key, shared by every pass of one loop. */
+export interface CiServeRuntime {
+    inflight: Map<string, Promise<CiServeJobState>>;
+}
+export declare const newCiServeRuntime: () => CiServeRuntime;
+/** The state key of a job. */
+export declare function ciServeKey(t: {
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+}): string;
+/** Where a serve keeps its state when `--state` names nowhere: beside the run events, in the repository's common git directory. */
+export declare function defaultCiServeStateDir(cwd: string): string;
+/** The state file, or a new one. */
+export declare function readCiServeState(file: string, fresh: Omit<CiServeState, "schema" | "jobs">): CiServeState;
+/**
+ * One poll of the forge, as triggers: an apply when the target's head moved
+ * since the last apply (none on the first poll, which only notes the head),
+ * then a plan for each open pull request head not yet planned, oldest pull
+ * request first. A job already in the state file is left out unless it
+ * failed and `rerunFailed` is set. The first poll's head is written to the
+ * state file.
+ */
+export declare function ciServeObserve(opts: CiServeOptions, rt?: CiServeRuntime): Promise<{
+    triggers: CiServeTrigger[];
+    events: CiServeEvent[];
+}>;
+/** What {@link ciServeSchedule} did with the triggers. */
+export interface CiServeScheduled {
+    /** Each job started, settling to its state entry. */
+    started: Promise<CiServeJobState>[];
+    events: CiServeEvent[];
+}
+/**
+ * Start the triggers' jobs, at most `maxJobs` at once with the jobs this
+ * process already runs. An apply first takes its group's lease. A trigger
+ * that can't start (over capacity, lease held, or already running here) is
+ * reported and not recorded, so the next poll finds it again.
+ */
+export declare function ciServeSchedule(opts: CiServeOptions, triggers: readonly CiServeTrigger[], rt?: CiServeRuntime): Promise<CiServeScheduled>;
+/** One pass: observe, schedule, and with `wait` wait for the jobs it started. */
+export declare function ciServePass(opts: CiServeOptions, rt?: CiServeRuntime, wait?: boolean): Promise<{
+    events: CiServeEvent[];
+    jobs: CiServeJobState[];
+}>;
+/**
+ * The loop: a pass every `intervalMs` until `signal` aborts, jobs running
+ * across passes up to `maxJobs`. A pass the forge fails is logged and the
+ * loop goes on. On abort it waits for the jobs that run.
+ */
+export declare function ciServeLoop(opts: CiServeOptions & {
+    intervalMs: number;
+    signal?: AbortSignal;
+}): Promise<void>;
+/** One line for an event, as `ci serve` prints it. */
+export declare function formatCiServeEvent(e: CiServeEvent): string;
+/**
+ * `chant ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]` (#4099):
+ * make the host's runner key when there is none, print its public half on
+ * stdout, and say whether the target's head lists it. With --trust, commit
+ * the runner entry on a branch of its own and push it for review.
+ */
+export declare function runnerKeySetupCommand(ctx: CommandContext): number;
+/** `--interval`: seconds, or a duration such as `30s` or `2m`. Default 30 seconds. */
+export declare function ciServeInterval(value: string | undefined): number;
+/** `chant ci serve` (#4095). */
+export declare function runCiServe(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=ci-serve.d.ts.map

package/dist/workspace/ci-serve.d.ts.map

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