@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/github/project-prs.d.ts

@@ -1,50 +1,18 @@
-/**
- * `agents projects prs <PROJECT>` — every OPEN pull request across a project's
- * attached repositories, as one machine-readable envelope for AGI Menu.
- *
- * Why this exists: `agents projects status`'s `openPrs` only carries the PRs the
- * fleet's own SESSIONS opened (the session rollup), so a project's board of open
- * PRs — drafts, other people's PRs, anything not tied to a live session — is
- * invisible to it. This reads the truth straight from GitHub.
- *
- * Design constraints (see docs conventions + the contract in
- * `.agents/scratch/contracts-status.json`):
- *   - Repos come ONLY from the ProjectDef's own attached slugs
- *     ({@link projectRepoSlugs}); `--repo` is refused unless it is one of them.
- *   - The list is REST + paginated (`gh api repos/{repo}/pulls?state=open
- *     --paginate`), includes drafts, and applies NO author filter — it is the
- *     whole open board, not this user's mergeable set. REST is the budget the
- *     fleet's GraphQL poll loops do not drain (PHNX-3501).
- *   - `checks` / `reviewDecision` are null in the list; `--number N` enriches
- *     exactly that one PR against its live head SHA (checks via REST
- *     {@link rollupForSha}, reviewDecision via a single lazy `gh pr view`).
- *   - A per-repo fetch failure is reported as `repositories[].error` and flips
- *     `partial` — it is NEVER relabeled as "zero open PRs".
- */
 import { type GhExec } from './pr-mergeable.js';
 import { type RollupItem } from './rest.js';
 import { type ProjectDef } from '../projects.js';
-/** The author of a PR, as the menu renders it (login + avatar). */
+import { type NpmView, type RepoRelease } from './release-drift.js';
 export interface ProjectPrAuthor {
     login: string;
     avatarUrl: string;
 }
-/**
- * Where a PR sits for a project whose repository is SHARED with another project
- * (a monorepo): `project` touches the paths this project claims, `repo-wide`
- * touches no sharing project's paths (root config, CI, docs). A PR that touches
- * only another project's paths is not listed at all. Null when the repository is
- * not shared, or this project claims all of it. Claims are {@link repoPathClaims},
- * the same ownership that attributes a session's cwd.
- */
 export type ProjectPrScope = 'project' | 'repo-wide';
-/** One open PR row. `checks`/`reviewDecision`/merge state are null unless the PR was enriched. */
+export type CiState = 'SUCCESS' | 'FAILURE' | 'PENDING' | 'ERROR' | 'EXPECTED';
 export interface ProjectPr {
     number: number;
     title: string;
     url: string;
     isDraft: boolean;
-    /** Upper-cased GitHub state — always `OPEN` here (only open PRs are listed). */
     state: string;
     createdAt: string;
     updatedAt: string;
@@ -54,120 +22,182 @@ export interface ProjectPr {
     headSha: string;
     body: string;
     scope: ProjectPrScope | null;
-    /** Populated only for the `--number` PR: GitHub's mergeability (null while it computes). */
     mergeable: boolean | null;
-    /** Populated only for the `--number` PR: `clean` | `unstable` | `blocked` | `behind` | `dirty` | `draft` | `unknown` … */
     mergeableState: string | null;
-    /** Populated only for the `--number` PR: the head-SHA status-check rollup. */
     checks: RollupItem[] | null;
-    /** Populated only for the `--number` PR: GitHub's computed review decision. */
     reviewDecision: string | null;
+    ciState: CiState | null;
+    failingChecks: string[];
+    autoMerge: ProjectPrAutoMerge | null;
+}
+export interface ProjectPrAutoMerge {
+    enabledBy: string;
+    method: string;
+}
+export interface RepoMergeAbility {
+    viewerIsAdmin: boolean;
+    adminBypass: boolean;
+    autoMergeAllowed: boolean;
+    methods: MergeMethod[];
+}
+export interface MergedPr {
+    number: number;
+    title: string;
+    url: string;
+    author: ProjectPrAuthor;
+    headRefName: string;
+    baseRefName: string;
+    mergedAt: string;
+    mergedBy: string | null;
+    mergeCommitSha: string | null;
+    ciState: CiState | null;
+    failingChecks: string[];
+    additions: number;
+    deletions: number;
+    scope: ProjectPrScope | null;
+}
+export interface DefaultBranchCi {
+    name: string;
+    sha: string;
+    ciState: CiState | null;
+    failingChecks: string[];
 }
-/** One repository's open PRs, or the error that stopped its fetch. */
 export interface ProjectRepoPrs {
     slug: string;
-    /** Other project definitions attached to this same repository. */
     sharedWith: string[];
     pullRequests: ProjectPr[];
-    /** Non-null when the fetch failed — the list is then NOT authoritative. */
+    merge: RepoMergeAbility | null;
+    recentlyMerged: MergedPr[];
+    defaultBranch: DefaultBranchCi | null;
+    ciError: string | null;
+    truncated: boolean;
+    release: RepoRelease | null;
+    releaseError: string | null;
     error: string | null;
 }
-/** The full `projects prs --json` envelope. */
 export interface ProjectPrsEnvelope {
     project: {
         name: string;
         linearProjectId: string | null;
     };
-    /** The authenticated GitHub login — what a "mine" filter compares `author.login` to. */
     viewer: string | null;
     repositories: ProjectRepoPrs[];
-    /** True when at least one repository fetch failed (its list is incomplete). */
     partial: boolean;
 }
-/** Options for one `projects prs` run. `number` requires `repo`. */
+export interface ProjectPrsContext {
+    nowMs?: number;
+    cacheDir?: string;
+    npmView?: NpmView;
+}
 export interface ProjectPrsOptions {
-    /** Restrict to one attached repo (canonicalized, membership-checked). */
     repo?: string;
-    /** Lazy detail: enrich exactly this PR's checks + reviewDecision. */
     number?: number;
 }
-/** Build a {@link ProjectPr} from the flattened jq row. checks/reviewDecision start null. */
 export declare function rowToProjectPr(row: Record<string, unknown>): ProjectPr;
-/**
- * Every OPEN PR for one repo, over REST, fully paginated, drafts included, no
- * author filter. `--paginate` follows Link headers; `--jq` streams one flattened
- * object per line so a multi-page result stays parseable.
- */
 export declare function listOpenPrs(repo: string, gh?: GhExec): Promise<ProjectPr[]>;
-/** One PR by number, over REST (`GET repos/{repo}/pulls/{n}`). Throws if it is gone. */
 export declare function fetchOnePr(repo: string, number: number, gh?: GhExec): Promise<ProjectPr>;
-/**
- * GitHub's computed review decision AND the PR's current head oid, from ONE lazy
- * `gh pr view` (GraphQL). reviewDecision is deliberately NOT REST-derived: it is
- * a branch-protection / CODEOWNERS decision REST cannot compute, and
- * approximating it could mislead a merge decision (PHNX-3501 note). `headRefOid`
- * rides the same call so the checks and the review verdict can be anchored to the
- * SAME head — a PR that advanced between the REST read and this call would
- * otherwise pair a stale check rollup with a current review. One call per
- * `--number`, never a poll loop, so it does not drain the shared GraphQL budget.
- */
 export declare function fetchReviewAndHead(repo: string, number: number, gh?: GhExec): Promise<{
     reviewDecision: string | null;
     headRefOid: string | null;
 }>;
-/**
- * Enrich one PR with its checks + reviewDecision, both anchored to the SAME head.
- * `gh pr view` gives the authoritative current head oid; the check rollup is run
- * against THAT (not the possibly-staler REST head SHA), and `headSha` is updated
- * to match, so checks and reviewDecision can never describe two different heads.
- */
 export declare function enrichPr(repo: string, pr: ProjectPr, gh?: GhExec): Promise<ProjectPr>;
-/**
- * Resolve which repositories a run targets, restricted to the project's own
- * attached repos. Slugs are canonicalized (a renamed repo lists nothing under
- * its old name — `phnx-labs/agents-cli` → `phnx-labs/agi-cli`). A `--repo` that
- * is not one of the project's attached repos (raw or canonical) is refused.
- */
+export declare const MERGED_WINDOW_DAYS = 7;
+export declare const MERGED_LIMIT = 20;
+export declare const MERGED_PAGE_CAP = 3;
+export declare const FAILING_CONCLUSIONS: Set<string>;
+export declare const FAILING_STATES: Set<string>;
+export interface CiSummary {
+    ciState: CiState | null;
+    failingChecks: string[];
+}
+export declare function ciFromRollupItems(items: readonly RollupItem[]): CiSummary;
+export declare function isPassingRollup(items: readonly RollupItem[]): boolean;
+export declare const PASSING_ROLLUP_TTL_MS: number;
+export declare const FAILING_ROLLUP_TTL_MS: number;
+export declare function isFinishedRollup(items: readonly RollupItem[]): boolean;
+export declare class KeyedCache<T> {
+    private readonly file;
+    private readonly sep;
+    private entries;
+    private dirty;
+    constructor(dir: string, name: string, sep: '@' | '#', isValid: (v: unknown) => v is T);
+    get(slug: string, id: string | number): T | undefined;
+    set(slug: string, id: string | number, value: T): void;
+    prune(slug: string, listed: ReadonlySet<string>): void;
+    save(): void;
+}
+interface MergedCandidate {
+    pr: MergedPr;
+    headSha: string;
+}
+export declare function listRecentlyMerged(repo: string, sinceMs: number, gh?: GhExec): Promise<{
+    merged: MergedCandidate[];
+    truncated: boolean;
+}>;
 export declare function resolveTargetSlugs(def: ProjectDef, repo: string | undefined, gh: GhExec): Promise<string[]>;
-/**
- * Classify one PR of a shared repository by the files it changes. `own` are
- * this project's prefixes, `others` every other sharing project's. Returns
- * null when the PR belongs only to another project.
- */
 export declare function scopeForFiles(files: readonly string[], own: readonly string[], others: readonly string[]): ProjectPrScope | null;
-/** The authenticated login, from a REST read gh caches for a day. */
 export declare function fetchViewer(gh?: GhExec): Promise<string | null>;
-/**
- * Build the full envelope. `number` (which the command requires alongside
- * `repo`) fetches and enriches exactly that one PR; otherwise every target
- * repo's open PRs are listed with checks/reviewDecision left null.
- *
- * `peers` are every project definition. A repository attached to more than one
- * project is scoped: when this project claims part of it ({@link repoPathClaims}),
- * its list keeps only PRs that touch those paths (`scope: project`) or touch no
- * sharing project's paths (`scope: repo-wide`).
- */
-export declare function buildProjectPrs(def: ProjectDef, opts?: ProjectPrsOptions, gh?: GhExec, peers?: readonly ProjectDef[]): Promise<ProjectPrsEnvelope>;
-/** How a PR is merged; the default is the first of these the repository allows. */
+export declare function buildProjectPrs(def: ProjectDef, opts?: ProjectPrsOptions, gh?: GhExec, peers?: readonly ProjectDef[], ctx?: ProjectPrsContext): Promise<ProjectPrsEnvelope>;
 export declare const MERGE_METHODS: readonly ["rebase", "squash", "merge"];
 export type MergeMethod = (typeof MERGE_METHODS)[number];
-/** The result of one `projects prs merge`. */
 export interface ProjectPrMergeResult {
     repo: string;
     number: number;
     method: MergeMethod;
     merged: boolean;
-    /** The merge commit SHA GitHub reports. */
     sha: string | null;
     message: string;
 }
-/** The first of {@link MERGE_METHODS} the repository allows. */
 export declare function defaultMergeMethod(repo: string, gh?: GhExec): Promise<MergeMethod>;
-/**
- * Merge one PR over REST (`PUT repos/{repo}/pulls/{n}/merge`), pinned to `sha`:
- * GitHub refuses with 409 when the head moved since the caller looked, so a push
- * that landed after the menu rendered is never merged unseen. Branch protection,
- * required checks and reviews are GitHub's to enforce; their refusal comes back
- * as `merged: false` with GitHub's own message.
- */
-export declare function mergeProjectPr(repo: string, number: number, sha: string, method: MergeMethod | undefined, gh?: GhExec): Promise<ProjectPrMergeResult>;
+export declare function readRepoMergeAbility(repo: string, gh?: GhExec): Promise<RepoMergeAbility>;
+export declare function ghFailure(err: unknown): string;
+export declare const BLOCKED_WITHOUT_ADMIN = "Blocked by branch protection; pass --admin to merge as an admin";
+export declare function mergeRefusalWithoutAdmin(state: string): string | null;
+export declare function readableMergeRefusal(message: string): string;
+export declare function mergeProjectPr(repo: string, number: number, sha: string, method: MergeMethod | undefined, opts?: {
+    admin?: boolean;
+}, gh?: GhExec): Promise<ProjectPrMergeResult>;
+export interface ProjectPrAutoMergeResult {
+    repo: string;
+    number: number;
+    enabled: boolean;
+    method: MergeMethod | null;
+    message: string;
+}
+export declare function setProjectPrAutoMerge(repo: string, number: number, opts: {
+    enable: true;
+    sha: string;
+    method?: MergeMethod;
+} | {
+    enable: false;
+}, gh?: GhExec): Promise<ProjectPrAutoMergeResult>;
+export interface ProjectPrReadyResult {
+    repo: string;
+    number: number;
+    ready: boolean;
+    sha: string | null;
+    message: string;
+}
+export declare function markProjectPrReady(repo: string, number: number, sha: string | undefined, gh?: GhExec): Promise<ProjectPrReadyResult>;
+export declare const OWN_PR_APPROVAL = "GitHub doesn't let you approve your own pull request";
+export interface ProjectPrReviewResult {
+    repo: string;
+    number: number;
+    event: 'APPROVE';
+    submitted: boolean;
+    sha: string | null;
+    id: number | null;
+    url: string | null;
+    message: string;
+}
+export declare function approveProjectPr(repo: string, number: number, sha: string, body: string | undefined, gh?: GhExec, viewerLogin?: () => Promise<string | null>): Promise<ProjectPrReviewResult>;
+export interface ProjectPrCommentResult {
+    repo: string;
+    number: number;
+    commented: boolean;
+    id: number | null;
+    url: string | null;
+    message: string;
+}
+export declare function commentOnProjectPr(repo: string, number: number, body: string, gh?: GhExec): Promise<ProjectPrCommentResult>;
+export {};