@juangadm/pre-post 1.0.0 → 1.1.0

package/dist/doctor.js

@@ -4,7 +4,7 @@
  * exactly one sentence telling the human what to do.
  */
 import { getBrowser, launchBrowserOrInstall } from './browser.js';
-import { hostOf } from './run.js';
+import { hostOf } from './url.js';
 import { BrowserNotFoundError, NeedsHumanError, isVercelResponse } from './errors.js';
 export { NeedsHumanError } from './errors.js';
 const INSTALL_HINT = 'Run: npx playwright-core install chromium-headless-shell   (or set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH), then re-run.';
@@ -37,14 +37,79 @@ export async function launchHeadedBrowser() {
         explainBrowserFailure(err);
     }
 }
-const DEV_PORTS = [3000, 3001, 3002, 5173, 5174, 4173, 4321, 8080, 8000, 5000, 4200];
 /**
- * Find a running local dev server. Returns its base URL or null.
+ * Ports worth asking, most likely first: the winner is the earliest that
+ * answers, so order is only ever a tie-break between two live servers.
+ *
+ * Order is not what keeps AirPlay out — `looksLikeDevServer` is, on every
+ * platform and at any position. 5000 sits last because on macOS it usually
+ * belongs to AirPlay Receiver rather than to a dev server, so it is the
+ * weakest guess in the list, not because being last protects anything. 7000,
+ * its sibling, is left out entirely: no framework defaults to it, so it has
+ * nothing to weigh against the noise.
  */
+const DEV_PORTS = [3000, 3001, 3002, 5173, 5174, 4173, 4321, 8080, 8000, 4200, 5000];
+/** An HTML document. `probeUrl` has already lowercased and dropped parameters. */
+function isHtml(contentType) {
+    return contentType === 'text/html' || contentType === 'application/xhtml+xml';
+}
+/**
+ * Is this a dev server, or just something listening?
+ *
+ * A reachable socket used to be enough, and it is not: on macOS, AirPlay
+ * Receiver holds port 5000 and answers every request 403 with no body. The
+ * probe adopted it, the 403 was read as access control, and the run advised
+ * signing in to a system service — in place of "no dev server is running",
+ * which is the one thing that was true. It bit precisely when nothing else was
+ * listening, the case the message exists to describe.
+ *
+ * So the bar is a plausible *app* response, not a reachable port:
+ *
+ * - 401/403 never qualifies. That is a wall or a stranger; either way there is
+ *   no site behind it to capture, and inferring a dev server from one is how
+ *   the above happened.
+ * - A redirect does. Locale prefixes and trailing slashes make it ordinary, and
+ *   there is no body to inspect, so the status is all there is to go on. If it
+ *   leads somewhere sign-in shaped, `landing.ts` catches that at capture time
+ *   with a message about the wall rather than about ports.
+ * - Anything else has to have served an HTML document. This deliberately keeps
+ *   a 404 or a 500 that renders a page: a dev server with no `/` route, or one
+ *   with a compile error, is still the dev server, and refusing it would send
+ *   someone hunting for a server they are already running.
+ */
+export function looksLikeDevServer(result) {
+    const { status, contentType } = result;
+    if (status === null)
+        return false;
+    if (status === 401 || status === 403)
+        return false;
+    if (status >= 300 && status < 400)
+        return true;
+    return isHtml(contentType);
+}
+/**
+ * Probe the usual ports and say what was found *and* what was passed over.
+ *
+ * `doctor` reports the ignored ports because "nothing on the usual ports" is
+ * confusing when something is plainly listening on one of them.
+ */
+export async function scanDevServers(ports = DEV_PORTS) {
+    const results = await Promise.all(ports.map(async (port) => ({
+        port,
+        ...(await probeUrl(`http://localhost:${port}/`, {}, { timeoutMs: 1500, redirect: 'manual' })),
+    })));
+    const scan = { url: null, ignored: [] };
+    for (const result of results) {
+        if (looksLikeDevServer(result))
+            scan.url ??= `http://localhost:${result.port}`;
+        else if (result.status !== null)
+            scan.ignored.push({ port: result.port, status: result.status });
+    }
+    return scan;
+}
+/** Find a running local dev server. Returns its base URL or null. */
 export async function detectDevServer(ports = DEV_PORTS) {
-    const results = await Promise.all(ports.map(async (p) => ({ p, ...(await probeUrl(`http://localhost:${p}/`, {}, { timeoutMs: 1500, redirect: 'manual' })) })));
-    const hit = results.find(r => r.status !== null);
-    return hit ? `http://localhost:${hit.p}` : null;
+    return (await scanDevServers(ports)).url;
 }
 /**
  * Probe a base URL with the headers we will use for capture.
@@ -52,7 +117,8 @@ export async function detectDevServer(ports = DEV_PORTS) {
 export async function probeUrl(url, headers = {}, options = {}) {
     try {
         const res = await fetch(url, { method: 'GET', headers, redirect: options.redirect ?? 'follow', signal: AbortSignal.timeout(options.timeoutMs ?? 10_000) });
-        return { status: res.status, vercel: isVercelResponse(res.headers) };
+        const contentType = res.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
+        return { status: res.status, vercel: isVercelResponse(res.headers), contentType: contentType || undefined };
     }
     catch {
         return { status: null, vercel: false };

package/dist/doctor.js.map

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

package/dist/git.d.ts

@@ -15,9 +15,47 @@ export declare function resolveOwnerRepo(cwd?: string): string;
 export declare function defaultBranch(cwd?: string): string;
 /** Merge base between HEAD and the default branch, or null when unknown. */
 export declare function mergeBase(cwd?: string): string | null;
+/** True when this clone was made with --depth, so its history may be missing. */
+export declare function isShallow(cwd?: string): boolean;
+/** The branch this work forked from: the CI hint first, then origin's default. */
+export declare function baseBranchName(cwd?: string): string;
 /**
- * Files changed on this branch relative to the default branch, plus anything
- * staged, unstaged, or untracked. Paths are relative to the repo root.
+ * git's empty tree. Diffing against it lists every tracked file, which is the
+ * honest answer in a repository whose first commit has not happened yet.
  */
-export declare function changedFiles(cwd?: string, diffTarget?: string): string[];
+export declare const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/** What a run diffs against, and how it was found. */
+export interface BaseResolution {
+    /** The commit the working tree is compared with. */
+    sha: string;
+    source: 'explicit' | 'merge-base' | 'fetched' | 'head';
+    /** The base branch it came from, when one is known. */
+    branch?: string;
+}
+export interface ResolveBaseOptions {
+    /** A ref the caller named; it wins outright. */
+    explicit?: string;
+    /** Allow one network fetch to repair a shallow clone. Default true. */
+    fetch?: boolean;
+    log?: (msg: string) => void;
+}
+/**
+ * The commit this branch forked from, or null when that cannot be established.
+ *
+ * Null is a real answer and callers must treat it as one: diffing against HEAD
+ * instead reports only uncommitted work, so a branch whose changes are
+ * committed comes back as "nothing changed" — the wrong answer, stated
+ * confidently.
+ */
+export declare function resolveBase(cwd?: string, opts?: ResolveBaseOptions): BaseResolution | null;
+/** `resolveBase`, with the one sentence a human needs when it comes back null. */
+export declare function requireBase(cwd: string, opts?: ResolveBaseOptions): BaseResolution;
+/**
+ * Files changed relative to `diffTarget`, plus anything staged, unstaged, or
+ * untracked. Paths are relative to the repo root.
+ *
+ * The target is required: working it out is `resolveBase`'s job, because
+ * guessing it wrong here is silent and reports an empty diff.
+ */
+export declare function changedFiles(cwd: string, diffTarget: string): string[];
 //# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,SAAgB,GAAG,MAAM,CAE/D;AAUD,wBAAgB,QAAQ,CAAC,GAAG,SAAgB,GAAG,MAAM,CAIpD;AAED,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAED,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASrD;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASlD;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,SAAgB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAS/E"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,SAAgB,GAAG,MAAM,CAE/D;AAUD,wBAAgB,QAAQ,CAAC,GAAG,SAAgB,GAAG,MAAM,CAIpD;AAED,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAED,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASrD;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASlD;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErD;AAOD,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAKnD;AAyBD;;;GAGG;AACH,eAAO,MAAM,UAAU,6CAA6C,CAAC;AAErE,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;IACvD,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,SAAgB,EAAE,IAAI,GAAE,kBAAuB,GAAG,cAAc,GAAG,IAAI,CA8BrG;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,cAAc,CAStF;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAStE"}

package/dist/git.js

@@ -2,6 +2,7 @@
  * Thin git helpers. Every call is a single short-lived subprocess.
  */
 import { execFileSync } from 'child_process';
+import { NeedsHumanError } from './errors.js';
 export function git(args, cwd = process.cwd()) {
     return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
@@ -62,21 +63,116 @@ export function defaultBranch(cwd) {
 }
 /** Merge base between HEAD and the default branch, or null when unknown. */
 export function mergeBase(cwd) {
-    const base = defaultBranch(cwd);
-    return tryGit(['merge-base', `origin/${base}`, 'HEAD'], cwd)
-        || tryGit(['merge-base', base, 'HEAD'], cwd);
+    return mergeBaseWith(defaultBranch(cwd), cwd);
+}
+function mergeBaseWith(branch, cwd) {
+    return tryGit(['merge-base', `origin/${branch}`, 'HEAD'], cwd)
+        || tryGit(['merge-base', branch, 'HEAD'], cwd);
+}
+/** True when this clone was made with --depth, so its history may be missing. */
+export function isShallow(cwd) {
+    return tryGit(['rev-parse', '--is-shallow-repository'], cwd) === 'true';
+}
+/** The branch this work forked from: the CI hint first, then origin's default. */
+export function baseBranchName(cwd) {
+    // GitHub Actions sets this on pull_request events, and it is more reliable
+    // than origin/HEAD in a checkout that has neither.
+    const env = process.env.GITHUB_BASE_REF?.trim();
+    return env || defaultBranch(cwd);
+}
+/**
+ * Make the base branch reachable in a clone that does not have it.
+ *
+ * Sandbox and web environments check a branch out with `--depth 1
+ * --single-branch`, which leaves no origin/<base> ref and no shared history to
+ * fork from. Widen in three steps, stopping as soon as a merge base appears, so
+ * the common case costs one shallow fetch rather than the whole history.
+ */
+function fetchBase(branch, cwd) {
+    const refspec = `+refs/heads/${branch}:refs/remotes/origin/${branch}`;
+    const attempts = [
+        ['fetch', '--no-tags', '--depth=50', 'origin', refspec],
+        ['fetch', '--no-tags', '--deepen=200', 'origin', refspec],
+        ['fetch', '--no-tags', '--unshallow', 'origin', refspec],
+    ];
+    for (const args of attempts) {
+        // A deepen or unshallow against a complete clone is an error, not a result.
+        if (tryGit(args, cwd) === null)
+            continue;
+        if (mergeBaseWith(branch, cwd))
+            return true;
+    }
+    return false;
+}
+/**
+ * git's empty tree. Diffing against it lists every tracked file, which is the
+ * honest answer in a repository whose first commit has not happened yet.
+ */
+export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * The commit this branch forked from, or null when that cannot be established.
+ *
+ * Null is a real answer and callers must treat it as one: diffing against HEAD
+ * instead reports only uncommitted work, so a branch whose changes are
+ * committed comes back as "nothing changed" — the wrong answer, stated
+ * confidently.
+ */
+export function resolveBase(cwd = process.cwd(), opts = {}) {
+    if (opts.explicit) {
+        const sha = tryGit(['rev-parse', '--verify', '--quiet', `${opts.explicit}^{commit}`], cwd);
+        if (!sha)
+            throw new NeedsHumanError(`--base ${opts.explicit} is not a commit in this repository.`);
+        return { sha, source: 'explicit' };
+    }
+    // No commits yet: everything in the tree is new, and there is nothing to
+    // fork from. Not a failure — a repository at its very beginning.
+    if (!headSha(cwd))
+        return { sha: EMPTY_TREE, source: 'head' };
+    const branch = baseBranchName(cwd);
+    const local = mergeBaseWith(branch, cwd);
+    if (local)
+        return { sha: local, source: 'merge-base', branch };
+    if (opts.fetch !== false) {
+        opts.log?.(`No local history for ${branch}; fetching it to see what this branch changed.`);
+        if (fetchBase(branch, cwd)) {
+            const sha = mergeBaseWith(branch, cwd);
+            if (sha)
+                return { sha, source: 'fetched', branch };
+        }
+    }
+    // Standing on the base branch with nothing to fork from: the change under
+    // review is whatever is uncommitted, which is what diffing HEAD reports.
+    if (currentBranch(cwd) === branch) {
+        const head = headSha(cwd);
+        if (head)
+            return { sha: head, source: 'head', branch };
+    }
+    return null;
+}
+/** `resolveBase`, with the one sentence a human needs when it comes back null. */
+export function requireBase(cwd, opts = {}) {
+    const base = resolveBase(cwd, opts);
+    if (base)
+        return base;
+    const branch = baseBranchName(cwd);
+    throw new NeedsHumanError(`Cannot tell what this branch changed: this clone shares no history with ${branch}` +
+        `${isShallow(cwd) ? ' (it is a shallow checkout)' : ''}. ` +
+        `Run \`git fetch origin ${branch}\`, or pass --base <ref>.`);
 }
 function lines(out) {
     return out ? out.split('\n').map(l => l.trim()).filter(Boolean) : [];
 }
 /**
- * Files changed on this branch relative to the default branch, plus anything
- * staged, unstaged, or untracked. Paths are relative to the repo root.
+ * Files changed relative to `diffTarget`, plus anything staged, unstaged, or
+ * untracked. Paths are relative to the repo root.
+ *
+ * The target is required: working it out is `resolveBase`'s job, because
+ * guessing it wrong here is silent and reports an empty diff.
  */
-export function changedFiles(cwd = process.cwd(), diffTarget) {
+export function changedFiles(cwd, diffTarget) {
     const files = new Set();
     const root = repoRoot(cwd);
-    const target = diffTarget || mergeBase(root) || 'HEAD';
+    const target = diffTarget;
     lines(tryGit(['diff', '--name-only', target], root)).forEach(f => files.add(f));
     lines(tryGit(['diff', '--name-only', '--cached'], root)).forEach(f => files.add(f));
     lines(tryGit(['diff', '--name-only'], root)).forEach(f => files.add(f));

package/dist/git.js.map

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

package/dist/github.d.ts

@@ -9,15 +9,90 @@
  */
 export { GitHubError } from './errors.js';
 export declare const API_BASE: string;
+/** Where a token came from. Which one it is decides how a rejection is fixed. */
+export type TokenSource = 'GH_TOKEN' | 'GITHUB_TOKEN' | 'gh';
+export interface FoundToken {
+    token: string;
+    source: TokenSource;
+}
+/**
+ * The token this run will use, and where it came from.
+ *
+ * The source is not bookkeeping: the env vars take precedence over the `gh`
+ * CLI, so advice aimed at the wrong one is advice that cannot work. Someone
+ * whose `GH_TOKEN` is refused gains nothing from `gh auth login`, because the
+ * variable still wins on the next run.
+ */
+export declare function findToken(): FoundToken | null;
 export declare function getToken(): string | null;
-/** A token, or the one sentence telling the human how to get one. */
-export declare function requireToken(purpose?: string): string;
+/** A token and its source, or the one sentence telling the human how to get one. */
+export declare function requireToken(purpose?: string): FoundToken;
 export declare class GitHub {
     private readonly token;
     private readonly base;
     constructor(token: string, base?: string);
     request<T = any>(method: string, path: string, body?: unknown): Promise<T>;
 }
+/** What one write attempt established about this token's access to a repository. */
+export type WriteAccess = 
+/** The token wrote an object. It may still be refused a ref by a ruleset. */
+{
+    writable: true;
+}
+/** GitHub refused the write. Nothing this run publishes will land. */
+ | {
+    writable: false;
+    reason: 'rejected';
+}
+/** Nobody answered, or answered something that is not about access. */
+ | {
+    writable: false;
+    reason: 'unknown';
+    detail: string;
+};
+/**
+ * Can this token write to `ownerRepo`?
+ *
+ * `getToken()` checks that a token exists, which is a different question. A
+ * GitHub Actions job that maps `secrets.GITHUB_TOKEN` gets one that reads
+ * everything this tool reads and writes nothing: measured on this repository,
+ * `GET /repos/juangadm/pre-post` answers 200 with `permissions.push: false`
+ * and `POST .../git/blobs` answers 403. Those reads are the ones `pr` makes
+ * before it captures, so without this the run spends its screenshots first and
+ * discovers the refusal after.
+ *
+ * The probe is the first write `publishAssets` makes, on the one piece of
+ * content that cannot add anything: the empty blob already exists in every
+ * repository, so a successful call stores nothing new. A read cannot stand in
+ * for it — `permissions.push` describes the account's access to the repository,
+ * not the scopes the token carries, so it can report `true` for a credential
+ * the write still refuses. That is the confident all-clear this check exists to
+ * avoid, which is why it writes.
+ *
+ * What it proves is bounded: the token may write objects. Creating the assets
+ * *ref* is a separate permission a ruleset can refuse, so `writable: true` is
+ * "not this failure", never "the publish will work".
+ */
+export declare function checkWriteAccess(gh: GitHub, ownerRepo: string): Promise<WriteAccess>;
+/**
+ * The one thing to do about a token that cannot publish.
+ *
+ * It follows the credential that was actually chosen, not just the
+ * environment. Being inside a runner does not make `permissions:` the fix: a
+ * workflow that sets `GH_TOKEN` to a PAT is refused by that PAT, and rewriting
+ * the job's permissions changes only the `GITHUB_TOKEN` the run never reaches.
+ * The same holds the other way round on a laptop, where `gh auth login` cannot
+ * help while an env var is shadowing it.
+ *
+ * The runner sentence names both permissions, though only `contents` is what
+ * this check tested. Naming `contents` alone would be advice that fails on its
+ * own terms: a `permissions:` block sets every scope it omits to none, so
+ * following it leaves a token that uploads the screenshots and is then refused
+ * the PR description — measured on this repository, `PATCH /pulls/23` answers
+ * 403 with only `contents: write` and 200 with `pull-requests: write` beside it.
+ * A second trip through a full capture is not worth the tighter sentence.
+ */
+export declare function cannotPublishHint(ownerRepo: string, source: TokenSource): string;
 export interface PullRequestRef {
     number: number;
     html_url: string;
@@ -27,6 +102,7 @@ export interface PullRequestRef {
     };
     base: {
         ref: string;
+        sha: string;
     };
     title: string;
 }
@@ -60,6 +136,20 @@ export interface CommentResult {
  * Create or update the single pre-post comment on a PR, identified by `marker`.
  */
 export declare function upsertStickyComment(gh: GitHub, ownerRepo: string, prNumber: number, body: string, marker: string): Promise<CommentResult>;
+export interface DescriptionResult {
+    html_url: string;
+    /** False when the PR body could not be edited and nothing was written. */
+    updated: boolean;
+}
+/**
+ * Write `body` into a marked block in the PR description, replacing the block
+ * from a previous run. The description is where reviewers look first, so this
+ * is preferred over a comment.
+ *
+ * Returns updated: false when the token cannot edit the PR (a fork, or no write
+ * access), so the caller can fall back to a comment instead of failing.
+ */
+export declare function upsertPrDescription(gh: GitHub, ownerRepo: string, prNumber: number, body: string, marker: string): Promise<DescriptionResult>;
 export interface PruneResult {
     removed: string[];
     kept: string[];

package/dist/github.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,eAAO,MAAM,QAAQ,QAAyD,CAAC;AAE/E,wBAAgB,QAAQ,IAAI,MAAM,GAAG,IAAI,CASxC;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,OAAO,SAAwB,GAAG,MAAM,CAIpE;AAED,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAU,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAApC,KAAK,EAAE,MAAM,EAAmB,IAAI,SAAW;IAEtE,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CA2BjF;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAO9G;AAED,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAE1K;AAED,MAAM,WAAW,SAAS;IACxB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3B;AAED,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGhF;AAeD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,CAqDxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CAexB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,UAAQ,GACb,OAAO,CAAC,WAAW,CAAC,CA8DtB"}
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"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"}