vouchington-tooling 0.5.1 → 0.6.0

package/dist/gha-pr-checkpoint/codec.d.mts

@@ -0,0 +1,58 @@
+export declare const CHECKPOINT_MARKER = "pr-checkpoint:v1";
+export type CheckpointStatus = 'queued' | 'running' | 'awaiting_verification' | 'failed' | 'deadline' | 'unresumable' | 'complete';
+export type Checkpoint = {
+    marker: string;
+    repository: string;
+    pr: number;
+    /** Absent on checkpoints posted before trigger ids were recorded; keep optional so resume can still parse them. */
+    triggerCommentId?: number;
+    headRef: string;
+    startSha: string;
+    sessionStartSha: string;
+    runId: string;
+    runUrl: string;
+    actor: string;
+    sessionId: string;
+    /** Absent from v1 checkpoints created before session URLs were exposed. */
+    sessionUrl?: string;
+    resumeSourceRunId: string;
+    status: CheckpointStatus;
+    createdAt: string;
+    updatedAt: string;
+};
+export type GitHubComment = {
+    id: number;
+    user?: {
+        login?: string;
+        type?: string;
+    };
+    performed_via_github_app?: {
+        slug?: string;
+    } | null;
+    body?: string;
+    created_at?: string;
+};
+export interface CheckpointCodecOptions {
+    marker?: string;
+    sessionIdPattern?: RegExp;
+}
+export interface TrustedCheckpointActor {
+    actor: string;
+    userType?: string;
+    appSlug?: string;
+}
+/**
+ * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
+ * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
+ * authored by the expected App identity.
+ */
+export declare function isTrustedCheckpointComment(comment: GitHubComment, context: TrustedCheckpointActor): boolean;
+export declare function renderCheckpoint(checkpoint: Checkpoint, options?: {
+    marker?: string;
+}): string;
+export declare function parseCheckpoint(body: string, options?: CheckpointCodecOptions): Checkpoint | undefined;
+export declare function validateCheckpoint(value: unknown, options?: CheckpointCodecOptions): Checkpoint | undefined;
+export declare function sortedCheckpointCandidates(comments: GitHubComment[], options?: CheckpointCodecOptions): {
+    comment: GitHubComment;
+    checkpoint: Checkpoint;
+}[];

package/dist/gha-pr-checkpoint/codec.mjs

@@ -0,0 +1,100 @@
+export const CHECKPOINT_MARKER = 'pr-checkpoint:v1';
+/**
+ * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
+ * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
+ * authored by the expected App identity.
+ */
+export function isTrustedCheckpointComment(comment, context) {
+    return (comment.user?.login === context.actor &&
+        comment.user?.type === (context.userType ?? 'Bot') &&
+        comment.performed_via_github_app?.slug === (context.appSlug ?? 'github-actions'));
+}
+export function renderCheckpoint(checkpoint, options = {}) {
+    const marker = options.marker ?? checkpoint.marker;
+    const payload = Buffer.from(JSON.stringify({ ...checkpoint, marker }), 'utf8').toString('base64url');
+    const session = checkpoint.sessionUrl
+        ? `[${checkpoint.sessionId}](${checkpoint.sessionUrl})`
+        : `\`${checkpoint.sessionId || 'pending'}\``;
+    return [
+        `👀 [View the automation workflow run](${checkpoint.runUrl}).`,
+        '',
+        `Status: \`${checkpoint.status}\` · Session: ${session}`,
+        '',
+        `<!-- ${marker} ${payload} -->`,
+    ].join('\n');
+}
+export function parseCheckpoint(body, options = {}) {
+    const marker = options.marker ?? CHECKPOINT_MARKER;
+    const match = body.match(new RegExp(`<!-- ${escapeRegExp(marker)} ([A-Za-z0-9_-]+) -->`, 'u'));
+    if (!match?.[1])
+        return undefined;
+    try {
+        return validateCheckpoint(JSON.parse(Buffer.from(match[1], 'base64url').toString('utf8')), options);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function validateCheckpoint(value, options = {}) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const checkpoint = value;
+    const marker = options.marker ?? CHECKPOINT_MARKER;
+    if (checkpoint.marker !== marker ||
+        !Number.isInteger(checkpoint.pr) ||
+        (checkpoint.triggerCommentId !== undefined && !Number.isInteger(checkpoint.triggerCommentId)) ||
+        typeof checkpoint.startSha !== 'string' ||
+        !/^[0-9a-f]{40}$/u.test(checkpoint.startSha) ||
+        typeof checkpoint.sessionStartSha !== 'string' ||
+        !/^[0-9a-f]{40}$/u.test(checkpoint.sessionStartSha) ||
+        typeof checkpoint.runId !== 'string' ||
+        !/^[0-9]+$/u.test(checkpoint.runId) ||
+        typeof checkpoint.resumeSourceRunId !== 'string' ||
+        (checkpoint.resumeSourceRunId !== '' && !/^[0-9]+$/u.test(checkpoint.resumeSourceRunId)) ||
+        typeof checkpoint.repository !== 'string' ||
+        typeof checkpoint.headRef !== 'string' ||
+        typeof checkpoint.runUrl !== 'string' ||
+        typeof checkpoint.actor !== 'string' ||
+        typeof checkpoint.sessionId !== 'string' ||
+        typeof checkpoint.createdAt !== 'string' ||
+        !Number.isFinite(Date.parse(checkpoint.createdAt)) ||
+        typeof checkpoint.updatedAt !== 'string' ||
+        !Number.isFinite(Date.parse(checkpoint.updatedAt)) ||
+        typeof checkpoint.status !== 'string' ||
+        ![
+            'queued',
+            'running',
+            'awaiting_verification',
+            'failed',
+            'deadline',
+            'unresumable',
+            'complete',
+        ].includes(checkpoint.status)) {
+        return undefined;
+    }
+    if (checkpoint.sessionId &&
+        options.sessionIdPattern &&
+        !matchesPattern(options.sessionIdPattern, checkpoint.sessionId)) {
+        return undefined;
+    }
+    if (checkpoint.sessionUrl !== undefined &&
+        (!URL.canParse(checkpoint.sessionUrl) || !checkpoint.sessionUrl.startsWith('https:'))) {
+        return undefined;
+    }
+    return checkpoint;
+}
+export function sortedCheckpointCandidates(comments, options = {}) {
+    return comments
+        .map((comment) => ({ comment, checkpoint: parseCheckpoint(comment.body ?? '', options) }))
+        .filter((candidate) => candidate.checkpoint !== undefined)
+        .toSorted((left, right) => {
+        const timestampOrder = String(right.comment.created_at ?? '').localeCompare(String(left.comment.created_at ?? ''));
+        return timestampOrder || right.comment.id - left.comment.id;
+    });
+}
+function matchesPattern(pattern, value) {
+    return new RegExp(pattern.source, pattern.flags.replaceAll(/[gy]/g, '')).test(value);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/gha-pr-checkpoint/index.d.mts

@@ -1,58 +1,3 @@
-export declare const CHECKPOINT_MARKER = "pr-checkpoint:v1";
-export type CheckpointStatus = 'queued' | 'running' | 'awaiting_verification' | 'failed' | 'deadline' | 'unresumable' | 'complete';
-export type Checkpoint = {
-    marker: string;
-    repository: string;
-    pr: number;
-    /** Absent on checkpoints posted before trigger ids were recorded; keep optional so resume can still parse them. */
-    triggerCommentId?: number;
-    headRef: string;
-    startSha: string;
-    sessionStartSha: string;
-    runId: string;
-    runUrl: string;
-    actor: string;
-    sessionId: string;
-    /** Absent from v1 checkpoints created before session URLs were exposed. */
-    sessionUrl?: string;
-    resumeSourceRunId: string;
-    status: CheckpointStatus;
-    createdAt: string;
-    updatedAt: string;
-};
-export type GitHubComment = {
-    id: number;
-    user?: {
-        login?: string;
-        type?: string;
-    };
-    performed_via_github_app?: {
-        slug?: string;
-    } | null;
-    body?: string;
-    created_at?: string;
-};
-export interface CheckpointCodecOptions {
-    marker?: string;
-    sessionIdPattern?: RegExp;
-}
-export interface TrustedCheckpointActor {
-    actor: string;
-    userType?: string;
-    appSlug?: string;
-}
-/**
- * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
- * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
- * authored by the expected App identity.
- */
-export declare function isTrustedCheckpointComment(comment: GitHubComment, context: TrustedCheckpointActor): boolean;
-export declare function renderCheckpoint(checkpoint: Checkpoint, options?: {
-    marker?: string;
-}): string;
-export declare function parseCheckpoint(body: string, options?: CheckpointCodecOptions): Checkpoint | undefined;
-export declare function validateCheckpoint(value: unknown, options?: CheckpointCodecOptions): Checkpoint | undefined;
-export declare function sortedCheckpointCandidates(comments: GitHubComment[], options?: CheckpointCodecOptions): {
-    comment: GitHubComment;
-    checkpoint: Checkpoint;
-}[];
+export * from './codec.mts';
+export { selectResumeCheckpoint, type CheckpointSelectionContext } from './resume.mts';
+export { updateExactCheckpoint, type CheckpointUpdateContext } from './update.mts';

package/dist/gha-pr-checkpoint/index.mjs

@@ -1,100 +1,3 @@
-export const CHECKPOINT_MARKER = 'pr-checkpoint:v1';
-/**
- * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
- * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
- * authored by the expected App identity.
- */
-export function isTrustedCheckpointComment(comment, context) {
-    return (comment.user?.login === context.actor &&
-        comment.user?.type === (context.userType ?? 'Bot') &&
-        comment.performed_via_github_app?.slug === (context.appSlug ?? 'github-actions'));
-}
-export function renderCheckpoint(checkpoint, options = {}) {
-    const marker = options.marker ?? checkpoint.marker;
-    const payload = Buffer.from(JSON.stringify({ ...checkpoint, marker }), 'utf8').toString('base64url');
-    const session = checkpoint.sessionUrl
-        ? `[${checkpoint.sessionId}](${checkpoint.sessionUrl})`
-        : `\`${checkpoint.sessionId || 'pending'}\``;
-    return [
-        `👀 [View the automation workflow run](${checkpoint.runUrl}).`,
-        '',
-        `Status: \`${checkpoint.status}\` · Session: ${session}`,
-        '',
-        `<!-- ${marker} ${payload} -->`,
-    ].join('\n');
-}
-export function parseCheckpoint(body, options = {}) {
-    const marker = options.marker ?? CHECKPOINT_MARKER;
-    const match = body.match(new RegExp(`<!-- ${escapeRegExp(marker)} ([A-Za-z0-9_-]+) -->`, 'u'));
-    if (!match?.[1])
-        return undefined;
-    try {
-        return validateCheckpoint(JSON.parse(Buffer.from(match[1], 'base64url').toString('utf8')), options);
-    }
-    catch {
-        return undefined;
-    }
-}
-export function validateCheckpoint(value, options = {}) {
-    if (!value || typeof value !== 'object')
-        return undefined;
-    const checkpoint = value;
-    const marker = options.marker ?? CHECKPOINT_MARKER;
-    if (checkpoint.marker !== marker ||
-        !Number.isInteger(checkpoint.pr) ||
-        (checkpoint.triggerCommentId !== undefined && !Number.isInteger(checkpoint.triggerCommentId)) ||
-        typeof checkpoint.startSha !== 'string' ||
-        !/^[0-9a-f]{40}$/u.test(checkpoint.startSha) ||
-        typeof checkpoint.sessionStartSha !== 'string' ||
-        !/^[0-9a-f]{40}$/u.test(checkpoint.sessionStartSha) ||
-        typeof checkpoint.runId !== 'string' ||
-        !/^[0-9]+$/u.test(checkpoint.runId) ||
-        typeof checkpoint.resumeSourceRunId !== 'string' ||
-        (checkpoint.resumeSourceRunId !== '' && !/^[0-9]+$/u.test(checkpoint.resumeSourceRunId)) ||
-        typeof checkpoint.repository !== 'string' ||
-        typeof checkpoint.headRef !== 'string' ||
-        typeof checkpoint.runUrl !== 'string' ||
-        typeof checkpoint.actor !== 'string' ||
-        typeof checkpoint.sessionId !== 'string' ||
-        typeof checkpoint.createdAt !== 'string' ||
-        !Number.isFinite(Date.parse(checkpoint.createdAt)) ||
-        typeof checkpoint.updatedAt !== 'string' ||
-        !Number.isFinite(Date.parse(checkpoint.updatedAt)) ||
-        typeof checkpoint.status !== 'string' ||
-        ![
-            'queued',
-            'running',
-            'awaiting_verification',
-            'failed',
-            'deadline',
-            'unresumable',
-            'complete',
-        ].includes(checkpoint.status)) {
-        return undefined;
-    }
-    if (checkpoint.sessionId &&
-        options.sessionIdPattern &&
-        !matchesPattern(options.sessionIdPattern, checkpoint.sessionId)) {
-        return undefined;
-    }
-    if (checkpoint.sessionUrl !== undefined &&
-        (!URL.canParse(checkpoint.sessionUrl) || !checkpoint.sessionUrl.startsWith('https:'))) {
-        return undefined;
-    }
-    return checkpoint;
-}
-export function sortedCheckpointCandidates(comments, options = {}) {
-    return comments
-        .map((comment) => ({ comment, checkpoint: parseCheckpoint(comment.body ?? '', options) }))
-        .filter((candidate) => candidate.checkpoint !== undefined)
-        .toSorted((left, right) => {
-        const timestampOrder = String(right.comment.created_at ?? '').localeCompare(String(left.comment.created_at ?? ''));
-        return timestampOrder || right.comment.id - left.comment.id;
-    });
-}
-function matchesPattern(pattern, value) {
-    return new RegExp(pattern.source, pattern.flags.replaceAll(/[gy]/g, '')).test(value);
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+export * from './codec.mjs';
+export { selectResumeCheckpoint } from './resume.mjs';
+export { updateExactCheckpoint } from './update.mjs';

package/dist/gha-pr-checkpoint/resume.d.mts

@@ -0,0 +1,14 @@
+import { type Checkpoint, type GitHubComment } from './codec.mts';
+export type CheckpointSelectionContext = {
+    repository: string;
+    pr: number;
+    headRef: string;
+    headSha: string;
+    actor: string;
+    isAncestor: (candidate: string, head: string) => boolean;
+    isShepherdRun: (runId: string) => boolean;
+};
+export declare function selectResumeCheckpoint(comments: GitHubComment[], context: CheckpointSelectionContext): {
+    checkpoint: Checkpoint;
+    commentId: number;
+} | undefined;

package/dist/gha-pr-checkpoint/resume.mjs

@@ -0,0 +1,21 @@
+import { isTrustedCheckpointComment, sortedCheckpointCandidates, } from './codec.mjs';
+export function selectResumeCheckpoint(comments, context) {
+    const candidates = sortedCheckpointCandidates(comments);
+    for (const { comment, checkpoint } of candidates) {
+        if (!isTrustedCheckpointComment(comment, context) ||
+            checkpoint.actor !== context.actor ||
+            checkpoint.repository !== context.repository ||
+            checkpoint.pr !== context.pr ||
+            checkpoint.headRef !== context.headRef ||
+            !checkpoint.sessionId ||
+            !context.isShepherdRun(checkpoint.runId) ||
+            !context.isAncestor(checkpoint.startSha, context.headSha) ||
+            !context.isAncestor(checkpoint.sessionStartSha, context.headSha)) {
+            continue;
+        }
+        if (checkpoint.status === 'complete' || checkpoint.status === 'unresumable')
+            return undefined;
+        return { checkpoint, commentId: comment.id };
+    }
+    return undefined;
+}

package/dist/gha-pr-checkpoint/update.d.mts

@@ -0,0 +1,15 @@
+import { type CheckpointStatus, type GitHubComment } from './codec.mts';
+export type CheckpointUpdateContext = {
+    actor: string;
+    commentId: number;
+    headRef: string;
+    headSha: string;
+    pr: number;
+    repository: string;
+    runId: string;
+    triggerCommentId: number;
+};
+export declare function updateExactCheckpoint(comment: GitHubComment, context: CheckpointUpdateContext, status: Extract<CheckpointStatus, 'failed' | 'running'>, session: {
+    id?: string;
+    url?: string;
+}): string;

package/dist/gha-pr-checkpoint/update.mjs

@@ -0,0 +1,30 @@
+import { isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, } from './codec.mjs';
+export function updateExactCheckpoint(comment, context, status, session) {
+    const checkpoint = parseCheckpoint(comment.body ?? '');
+    if (!checkpoint ||
+        comment.id !== context.commentId ||
+        !isTrustedCheckpointComment(comment, context) ||
+        checkpoint.actor !== context.actor ||
+        checkpoint.repository !== context.repository ||
+        checkpoint.pr !== context.pr ||
+        checkpoint.triggerCommentId !== context.triggerCommentId ||
+        checkpoint.runId !== context.runId ||
+        checkpoint.headRef !== context.headRef ||
+        checkpoint.startSha !== context.headSha) {
+        throw new Error('Checkpoint comment does not match the active run binding');
+    }
+    if (status === 'running' && (!session.id || !session.url)) {
+        throw new Error('Running checkpoint requires a session id and URL');
+    }
+    if (session.url && (!URL.canParse(session.url) || !session.url.startsWith('https:'))) {
+        throw new Error('Session URL must be a parseable https URL');
+    }
+    const next = {
+        ...checkpoint,
+        ...(session.id ? { sessionId: session.id } : {}),
+        ...(session.url ? { sessionUrl: session.url } : {}),
+        status,
+        updatedAt: new Date().toISOString(),
+    };
+    return renderCheckpoint(next);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {