@juangadm/pre-post 0.3.0 → 1.1.0

package/dist/git.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Thin git helpers. Every call is a single short-lived subprocess.
+ */
+export declare function git(args: string[], cwd?: string): string;
+export declare function repoRoot(cwd?: string): string;
+export declare function currentBranch(cwd?: string): string | null;
+export declare function headSha(cwd?: string): string | null;
+/**
+ * Parse "owner/repo" from a remote URL. Supports HTTPS, SSH, and proxy URLs
+ * whose last two path segments are owner/repo.
+ */
+export declare function parseOwnerRepo(remoteUrl: string): string | null;
+export declare function resolveOwnerRepo(cwd?: string): string;
+/** Default branch of origin (main/master/...), best effort. */
+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;
+/**
+ * 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 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,182 @@
+/**
+ * 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();
+}
+function tryGit(args, cwd) {
+    try {
+        return git(args, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+export function repoRoot(cwd = process.cwd()) {
+    const root = tryGit(['rev-parse', '--show-toplevel'], cwd);
+    if (!root)
+        throw new Error('Not inside a git repository.');
+    return root;
+}
+export function currentBranch(cwd) {
+    const b = tryGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    return b && b !== 'HEAD' ? b : null;
+}
+export function headSha(cwd) {
+    return tryGit(['rev-parse', 'HEAD'], cwd);
+}
+/**
+ * Parse "owner/repo" from a remote URL. Supports HTTPS, SSH, and proxy URLs
+ * whose last two path segments are owner/repo.
+ */
+export function parseOwnerRepo(remoteUrl) {
+    const std = remoteUrl.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+    if (std)
+        return std[1];
+    const fallback = remoteUrl.match(/\/([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+    return fallback ? fallback[1] : null;
+}
+export function resolveOwnerRepo(cwd) {
+    const env = process.env.GH_REPO || process.env.GITHUB_REPOSITORY;
+    if (env)
+        return env;
+    const url = tryGit(['remote', 'get-url', 'origin'], cwd);
+    const parsed = url ? parseOwnerRepo(url) : null;
+    if (!parsed) {
+        throw new Error('Cannot determine GitHub repository. Set GH_REPO=owner/repo.');
+    }
+    return parsed;
+}
+/** Default branch of origin (main/master/...), best effort. */
+export function defaultBranch(cwd) {
+    const ref = tryGit(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], cwd);
+    if (ref)
+        return ref.replace(/^origin\//, '');
+    const found = lines(tryGit([
+        'for-each-ref', '--format=%(refname:short)',
+        'refs/remotes/origin/main', 'refs/remotes/origin/master', 'refs/heads/main', 'refs/heads/master',
+    ], cwd));
+    const first = found[0]?.replace(/^origin\//, '');
+    return first || 'main';
+}
+/** Merge base between HEAD and the default branch, or null when unknown. */
+export function mergeBase(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 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, diffTarget) {
+    const files = new Set();
+    const root = repoRoot(cwd);
+    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));
+    lines(tryGit(['ls-files', '--others', '--exclude-standard'], root)).forEach(f => files.add(f));
+    return Array.from(files);
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

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

package/dist/github.d.ts

@@ -0,0 +1,163 @@
+/**
+ * GitHub REST client used for:
+ *   - finding the open PR for a branch
+ *   - publishing screenshots to an orphan assets branch (Git Data API, one commit per run)
+ *   - upserting a sticky PR comment
+ *   - pruning old assets
+ *
+ * Authentication: GH_TOKEN / GITHUB_TOKEN, else the gh CLI's stored token.
+ */
+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 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;
+    head: {
+        sha: string;
+        ref: string;
+    };
+    base: {
+        ref: string;
+        sha: string;
+    };
+    title: string;
+}
+export declare function findOpenPr(gh: GitHub, ownerRepo: string, branch: string): Promise<PullRequestRef | null>;
+export declare function getPr(gh: GitHub, ownerRepo: string, number: number): Promise<PullRequestRef & {
+    state: string;
+    closed_at: string | null;
+    merged_at: string | null;
+}>;
+export interface AssetFile {
+    /** Path inside the assets branch, e.g. "pr-42/20260115-1200/home-desktop-post.png" */
+    path: string;
+    content: Buffer;
+}
+export interface PublishResult {
+    sha: string;
+    /** path → raw-rendering blob URL */
+    urls: Map<string, string>;
+}
+export declare function blobUrl(ownerRepo: string, sha: string, filePath: string): string;
+/**
+ * Publish files to `branch` as a single commit. Creates the branch as an
+ * orphan (no parents) when it does not exist. Retries once on a ref race.
+ */
+export declare function publishAssets(gh: GitHub, ownerRepo: string, branch: string, files: AssetFile[], message: string): Promise<PublishResult>;
+export interface CommentResult {
+    html_url: string;
+    created: boolean;
+}
+/**
+ * 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[];
+    sha?: string;
+}
+/**
+ * Remove `pr-<n>/` folders on the assets branch whose PR closed more than
+ * `olderThanDays` ago. One commit; no history rewrite.
+ */
+export declare function pruneAssets(gh: GitHub, ownerRepo: string, branch: string, olderThanDays: number, dryRun?: boolean): Promise<PruneResult>;
+//# sourceMappingURL=github.d.ts.map

package/dist/github.d.ts.map

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