vouchington-tooling 0.0.16 → 0.0.18

package/dist/index.d.mts

@@ -33,6 +33,8 @@ export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mts'
 export type { AstGrepRuleInvocation, RunAstGrepRuleOptions } from './ast-grep-rule/index.mts';
 export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mts';
 export type { CommentableIndex, CommentableLine, LineKind, PayloadRequirement, ReviewComment, ReviewFile, ReviewSide, SanitizedReview, } from './gha-review-payload/index.mts';
+export { CLAUDE_OIDC_AUDIENCE, createActionsClaudeTokenIo, mintClaudeAppToken, PostReviewError, requireEnv, resolveReviewPostToken, revokeClaudeAppToken, runPostReview, runPostReviewCli, withClaudeAppToken, } from './gha-post-review/index.mts';
+export type { ClaudeTokenIo, PostResult, PostReviewIo, PullFile, ReviewPostToken, } from './gha-post-review/index.mts';
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mts';
 export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mts';
 export type { ExpectedTransportIdentity, ObjectSigner, PresignIdentity, TransportControl, } from './coverage-transport/index.mts';
@@ -49,3 +51,8 @@ export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderC
 export type { Checkpoint, CheckpointCodecOptions, GitHubComment, } from './gha-pr-checkpoint/index.mts';
 export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mts';
 export type { WorkspaceGatesOptions } from './workspace-gates/index.mts';
+export { validateNugetUpdate } from './nuget-central-version/index.mts';
+export { normalizeSwiftSource } from './swift-semantic-equal/index.mts';
+export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mts';
+export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
+export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';

package/dist/index.mjs

@@ -19,6 +19,7 @@ export { escapeSpreadsheetFormula, parseCsvRows, streamCsvRows, stripCsvBom } fr
 export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, ResponseBodyTooLargeError, } from './http-body/index.mjs';
 export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mjs';
 export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mjs';
+export { CLAUDE_OIDC_AUDIENCE, createActionsClaudeTokenIo, mintClaudeAppToken, PostReviewError, requireEnv, resolveReviewPostToken, revokeClaudeAppToken, runPostReview, runPostReviewCli, withClaudeAppToken, } from './gha-post-review/index.mjs';
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mjs';
 export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mjs';
 export { EPOCH_PRUNED_AT, normalizeDeployedLayer, pruneDeployedRuntimeDeps, restoreDeployedWorkspacePackages, } from './pnpm-deploy/index.mjs';
@@ -28,3 +29,7 @@ export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-l
 export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mjs';
 export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, sortedCheckpointCandidates, validateCheckpoint, } from './gha-pr-checkpoint/index.mjs';
 export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mjs';
+export { validateNugetUpdate } from './nuget-central-version/index.mjs';
+export { normalizeSwiftSource } from './swift-semantic-equal/index.mjs';
+export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mjs';
+export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mjs';

package/dist/nuget-central-version/cli.d.mts

@@ -0,0 +1 @@
+export declare function runNugetCentralVersionCli(args: readonly string[]): void;

package/dist/nuget-central-version/cli.mjs

@@ -0,0 +1,11 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { validateNugetUpdate } from './index.mjs';
+export function runNugetCentralVersionCli(args) {
+    const [trustedPath, candidatePath, metadataPath, outputPath] = args;
+    if (!trustedPath || !candidatePath || !metadataPath || !outputPath || args.length !== 4) {
+        throw new Error('Usage: vouchington nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>');
+    }
+    const candidateSource = readFileSync(candidatePath, 'utf8');
+    validateNugetUpdate(readFileSync(trustedPath, 'utf8'), candidateSource, readFileSync(metadataPath, 'utf8'));
+    writeFileSync(outputPath, candidateSource);
+}

package/dist/nuget-central-version/index.d.mts

@@ -0,0 +1 @@
+export declare function validateNugetUpdate(trustedSource: string, candidateSource: string, metadataSource: string): string[];

package/dist/nuget-central-version/index.mjs

@@ -0,0 +1,74 @@
+const packageVersionPattern = /<PackageVersion\s+Include="(?<name>[^"]+)"\s+Version="(?<version>[^"]+)"\s*\/>/g;
+const literalNugetVersionPattern = /^\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+function parseVersions(source) {
+    const versions = new Map();
+    for (const match of source.matchAll(packageVersionPattern)) {
+        const name = match.groups?.name;
+        const version = match.groups?.version;
+        if (!name || !version || versions.has(name)) {
+            throw new Error('Directory.Packages.props must contain unique PackageVersion entries');
+        }
+        versions.set(name, { literal: match[0], version });
+    }
+    if (versions.size === 0)
+        throw new Error('Directory.Packages.props has no PackageVersion entries');
+    return versions;
+}
+export function validateNugetUpdate(trustedSource, candidateSource, metadataSource) {
+    const trusted = parseVersions(trustedSource);
+    const candidate = parseVersions(candidateSource);
+    if (candidate.size !== trusted.size) {
+        throw new Error('Dependabot may not add or remove central package declarations');
+    }
+    const changed = [];
+    let expected = trustedSource;
+    for (const [name, trustedEntry] of trusted) {
+        const candidateEntry = candidate.get(name);
+        if (!candidateEntry)
+            throw new Error(`Dependabot removed central package ${name}`);
+        if (candidateEntry.version === trustedEntry.version)
+            continue;
+        if (!literalNugetVersionPattern.test(trustedEntry.version)) {
+            throw new Error(`Dependabot may not change MSBuild-managed version for ${name}`);
+        }
+        if (!literalNugetVersionPattern.test(candidateEntry.version)) {
+            throw new Error(`Dependabot proposed a non-literal NuGet version for ${name}`);
+        }
+        changed.push(name);
+        expected = expected.replace(trustedEntry.literal, trustedEntry.literal.replace(`Version="${trustedEntry.version}"`, `Version="${candidateEntry.version}"`));
+    }
+    if (changed.length === 0)
+        throw new Error('Dependabot NuGet update changed no package versions');
+    if (candidateSource !== expected) {
+        throw new Error('Dependabot may change only literal central PackageVersion values');
+    }
+    const metadata = JSON.parse(metadataSource);
+    if (!Array.isArray(metadata))
+        throw new Error('Dependabot NuGet metadata must be an array');
+    const metadataByName = new Map();
+    for (const update of metadata) {
+        const name = update.dependencyName?.toLowerCase();
+        if (!name || !update.prevVersion || !update.newVersion || metadataByName.has(name)) {
+            throw new Error('Dependabot NuGet metadata must identify every changed package exactly once');
+        }
+        metadataByName.set(name, update);
+    }
+    const metadataNames = [...metadataByName.keys()].toSorted();
+    const changedNames = changed.map((name) => name.toLowerCase()).toSorted();
+    if (metadataNames.length !== changedNames.length ||
+        new Set(metadataNames).size !== metadataNames.length) {
+        throw new Error('Dependabot NuGet metadata must identify every changed package exactly once');
+    }
+    if (!metadataNames.every((name, index) => name === changedNames[index])) {
+        throw new Error('Dependabot NuGet metadata does not match the changed central packages');
+    }
+    for (const name of changed) {
+        const update = metadataByName.get(name.toLowerCase());
+        const trustedVersion = trusted.get(name)?.version;
+        const candidateVersion = candidate.get(name)?.version;
+        if (update?.prevVersion !== trustedVersion || update?.newVersion !== candidateVersion) {
+            throw new Error(`Dependabot NuGet metadata versions do not match ${name}`);
+        }
+    }
+    return changed.toSorted();
+}

package/dist/swift-resolved-pin-delta/index.d.mts

@@ -0,0 +1,18 @@
+export type ResolvedPin = {
+    identity?: string;
+    kind?: string;
+    location?: string;
+    state?: {
+        revision?: string;
+        version?: string;
+    };
+};
+export type ResolvedDocument = {
+    originHash?: string;
+    pins?: ResolvedPin[];
+    version?: number;
+};
+export type ValidateResolvedPinDeltaOptions = {
+    requiredIdentity?: string;
+};
+export declare function validateResolvedPinDelta(trustedResolved: ResolvedDocument, candidateResolved: ResolvedDocument, options?: ValidateResolvedPinDeltaOptions): void;

package/dist/swift-resolved-pin-delta/index.mjs

@@ -0,0 +1,63 @@
+function isExactSemver(value) {
+    const match = value?.match(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?<prerelease>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+    return Boolean(match &&
+        !match.groups?.prerelease
+            ?.split('.')
+            .some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier[0] === '0'));
+}
+function exactPins(resolved) {
+    if (!Array.isArray(resolved.pins))
+        throw new Error('Package.resolved must contain pins');
+    const pins = new Map();
+    for (const pin of resolved.pins) {
+        const state = pin.state;
+        if (!pin.identity?.match(/^[a-z0-9][a-z0-9.-]*$/) ||
+            pin.kind !== 'remoteSourceControl' ||
+            !pin.location?.match(/^https:\/\/[^\s]+$/) ||
+            !state?.revision?.match(/^[a-f0-9]{40}$/) ||
+            !isExactSemver(state.version) ||
+            Object.keys(pin).toSorted().join(',') !== 'identity,kind,location,state' ||
+            Object.keys(state).toSorted().join(',') !== 'revision,version') {
+            throw new Error('Package.resolved pins must remain fully specified exact pins');
+        }
+        if (pins.has(pin.identity)) {
+            throw new Error('Package.resolved must contain unique pin identities');
+        }
+        pins.set(pin.identity, pin);
+    }
+    return pins;
+}
+function canonicalPin(pin) {
+    return JSON.stringify({
+        identity: pin.identity,
+        kind: pin.kind,
+        location: pin.location,
+        state: { revision: pin.state.revision, version: pin.state.version },
+    });
+}
+export function validateResolvedPinDelta(trustedResolved, candidateResolved, options = {}) {
+    const requiredIdentity = options.requiredIdentity ?? 'skip';
+    if (trustedResolved.version !== 3 ||
+        candidateResolved.version !== 3 ||
+        !candidateResolved.originHash?.match(/^[a-f0-9]{64}$/)) {
+        throw new Error('Package.resolved must remain a version 3 lock with an origin hash');
+    }
+    const trustedPins = exactPins(trustedResolved);
+    const candidatePins = exactPins(candidateResolved);
+    const trustedRequired = trustedPins.get(requiredIdentity);
+    const candidateRequired = candidatePins.get(requiredIdentity);
+    if (!trustedRequired ||
+        !candidateRequired ||
+        trustedRequired.kind !== candidateRequired.kind ||
+        trustedRequired.location !== candidateRequired.location) {
+        throw new Error(`Package.resolved must keep the trusted ${requiredIdentity} source`);
+    }
+    for (const [identity, trustedPin] of trustedPins) {
+        if (identity === requiredIdentity)
+            continue;
+        const candidatePin = candidatePins.get(identity);
+        if (!candidatePin || canonicalPin(candidatePin) !== canonicalPin(trustedPin)) {
+            throw new Error(`Package.resolved must keep every trusted non-${requiredIdentity} pin unchanged`);
+        }
+    }
+}

package/dist/swift-semantic-equal/cli.d.mts

@@ -0,0 +1,2 @@
+import { execFileSync } from 'node:child_process';
+export declare function runSwiftSemanticEqualCli(args: readonly string[], gitShow?: typeof execFileSync): number;

package/dist/swift-semantic-equal/cli.mjs

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process';
+import { normalizeSwiftSource } from './normalize.mjs';
+export function runSwiftSemanticEqualCli(args, gitShow = execFileSync) {
+    const [base, head, file] = args;
+    if (!base || !head || !file || args.length !== 3 || !file.endsWith('.swift')) {
+        return 1;
+    }
+    try {
+        const baseSource = gitShow('git', ['show', `${base}:${file}`], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const headSource = gitShow('git', ['show', `${head}:${file}`], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return normalizeSwiftSource(String(baseSource)) === normalizeSwiftSource(String(headSource))
+            ? 0
+            : 1;
+    }
+    catch {
+        return 1;
+    }
+}

package/dist/swift-semantic-equal/index.d.mts

@@ -0,0 +1 @@
+export { normalizeSwiftSource } from './normalize.mts';

package/dist/swift-semantic-equal/index.mjs

@@ -0,0 +1 @@
+export { normalizeSwiftSource } from './normalize.mjs';

package/dist/swift-semantic-equal/normalize.d.mts

@@ -0,0 +1 @@
+export declare function normalizeSwiftSource(source: string): string;

package/dist/swift-semantic-equal/normalize.mjs

@@ -0,0 +1,108 @@
+export function normalizeSwiftSource(source) {
+    let normalized = '';
+    let index = 0;
+    while (index < source.length) {
+        const char = source[index];
+        if (char === undefined || /\s/u.test(char)) {
+            index += 1;
+            continue;
+        }
+        if (source.startsWith('//', index)) {
+            index = skipLineComment(source, index);
+            continue;
+        }
+        if (source.startsWith('/*', index)) {
+            index = skipBlockComment(source, index);
+            continue;
+        }
+        const hashCount = countLeadingHashes(source, index);
+        const afterHashes = source[index + hashCount];
+        if (afterHashes === '"') {
+            const literal = readSwiftStringLiteral(source, index, hashCount);
+            if (literal) {
+                normalized += literal.text;
+                index = literal.end;
+                continue;
+            }
+        }
+        if (afterHashes === '/') {
+            const literal = readSwiftRegexLiteral(source, index, hashCount, normalized);
+            if (literal) {
+                normalized += literal.text;
+                index = literal.end;
+                continue;
+            }
+        }
+        normalized += char;
+        index += 1;
+    }
+    return normalized;
+}
+function countLeadingHashes(source, start) {
+    let count = 0;
+    while (source[start + count] === '#')
+        count += 1;
+    return count;
+}
+function skipLineComment(source, start) {
+    const end = source.indexOf('\n', start + 2);
+    return end === -1 ? source.length : end + 1;
+}
+function skipBlockComment(source, start) {
+    let depth = 1;
+    let index = start + 2;
+    while (index < source.length && depth > 0) {
+        if (source.startsWith('/*', index)) {
+            depth += 1;
+            index += 2;
+        }
+        else if (source.startsWith('*/', index)) {
+            depth -= 1;
+            index += 2;
+        }
+        else {
+            index += 1;
+        }
+    }
+    return index;
+}
+function readSwiftStringLiteral(source, start, hashCount) {
+    const openingQuote = start + hashCount;
+    const isTripleQuoted = source.startsWith('"""', openingQuote);
+    const openerLength = hashCount + (isTripleQuoted ? 3 : 1);
+    const closer = `${isTripleQuoted ? '"""' : '"'}${'#'.repeat(hashCount)}`;
+    let index = start + openerLength;
+    while (index < source.length) {
+        if (!isTripleQuoted && hashCount === 0 && source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source.startsWith(closer, index)) {
+            return { end: index + closer.length, text: source.slice(start, index + closer.length) };
+        }
+        index += 1;
+    }
+    return null;
+}
+function readSwiftRegexLiteral(source, start, hashCount, normalizedPrefix) {
+    if (hashCount === 0 && !canStartBareRegex(normalizedPrefix))
+        return null;
+    const closer = `/${'#'.repeat(hashCount)}`;
+    let index = start + hashCount + 1;
+    while (index < source.length) {
+        if (hashCount === 0 && source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source.startsWith(closer, index)) {
+            return { end: index + closer.length, text: source.slice(start, index + closer.length) };
+        }
+        index += 1;
+    }
+    return null;
+}
+function canStartBareRegex(normalizedPrefix) {
+    if (normalizedPrefix.length === 0)
+        return true;
+    return /[({[=,:;!&|?]/u.test(normalizedPrefix.at(-1));
+}

package/dist/swift-source-offset/index.d.mts

@@ -0,0 +1,2 @@
+export declare function isSwiftCodeOffset(source: string, offset: number): boolean;
+export declare function parseUniqueSwiftBinaryTargetChecksum(source: string, targetName: string, expectedUrl: string): string | undefined;

package/dist/swift-source-offset/index.mjs

@@ -0,0 +1,68 @@
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function isSwiftCodeOffset(source, offset) {
+    let blockCommentDepth = 0;
+    let escaped = false;
+    let inLineComment = false;
+    let inMultilineString = false;
+    let inString = false;
+    for (let index = 0; index < offset; index += 1) {
+        const character = source[index];
+        const pair = source.slice(index, index + 2);
+        const triple = source.slice(index, index + 3);
+        if (inLineComment) {
+            if (character === '\n')
+                inLineComment = false;
+            continue;
+        }
+        if (blockCommentDepth > 0) {
+            if (pair === '/*') {
+                blockCommentDepth += 1;
+                index += 1;
+            }
+            else if (pair === '*/') {
+                blockCommentDepth -= 1;
+                index += 1;
+            }
+            continue;
+        }
+        if (inMultilineString) {
+            if (triple === '"""') {
+                inMultilineString = false;
+                index += 2;
+            }
+            continue;
+        }
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (character === '\\')
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (pair === '//') {
+            inLineComment = true;
+            index += 1;
+        }
+        else if (pair === '/*') {
+            blockCommentDepth = 1;
+            index += 1;
+        }
+        else if (triple === '"""') {
+            inMultilineString = true;
+            index += 2;
+        }
+        else if (character === '"') {
+            inString = true;
+        }
+    }
+    return !inLineComment && blockCommentDepth === 0 && !inMultilineString && !inString;
+}
+export function parseUniqueSwiftBinaryTargetChecksum(source, targetName, expectedUrl) {
+    const expression = new RegExp(`^\\s*package\\.targets\\s*\\+=\\s*\\[\\s*\\.binaryTarget\\(\\s*name:\\s*"${escapeRegExp(targetName)}"\\s*,\\s*url:\\s*"${escapeRegExp(expectedUrl)}"\\s*,\\s*checksum:\\s*"(?<checksum>[a-f0-9]{64})"\\s*\\)\\s*\\]\\s*$`, 'gm');
+    const matches = [...source.matchAll(expression)].filter((match) => match.index !== undefined && isSwiftCodeOffset(source, match.index));
+    return matches.length === 1 ? matches[0]?.groups?.checksum : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -125,6 +125,11 @@
       "import": "./dist/gha-review-payload/index.mjs",
       "default": "./dist/gha-review-payload/index.mjs"
     },
+    "./gha-post-review": {
+      "types": "./dist/gha-post-review/index.d.mts",
+      "import": "./dist/gha-post-review/index.mjs",
+      "default": "./dist/gha-post-review/index.mjs"
+    },
     "./http-link-pagination": {
       "types": "./dist/http-link-pagination/index.d.mts",
       "import": "./dist/http-link-pagination/index.mjs",
@@ -170,6 +175,26 @@
       "import": "./dist/workspace-gates/index.mjs",
       "default": "./dist/workspace-gates/index.mjs"
     },
+    "./nuget-central-version": {
+      "types": "./dist/nuget-central-version/index.d.mts",
+      "import": "./dist/nuget-central-version/index.mjs",
+      "default": "./dist/nuget-central-version/index.mjs"
+    },
+    "./swift-semantic-equal": {
+      "types": "./dist/swift-semantic-equal/index.d.mts",
+      "import": "./dist/swift-semantic-equal/index.mjs",
+      "default": "./dist/swift-semantic-equal/index.mjs"
+    },
+    "./swift-source-offset": {
+      "types": "./dist/swift-source-offset/index.d.mts",
+      "import": "./dist/swift-source-offset/index.mjs",
+      "default": "./dist/swift-source-offset/index.mjs"
+    },
+    "./swift-resolved-pin-delta": {
+      "types": "./dist/swift-resolved-pin-delta/index.d.mts",
+      "import": "./dist/swift-resolved-pin-delta/index.mjs",
+      "default": "./dist/swift-resolved-pin-delta/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/scripts/gha/ghcr-package-retention.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Keep the most recent KEEP_MIN non-protected GHCR package versions, plus any
+# version whose tags match the protected prefix/contains rules.
+set -euo pipefail
+
+KEEP_MIN="${KEEP_MIN:-10}"
+OWNER_TYPE="${GHCR_OWNER_TYPE:-user}"
+OWNER="${GHCR_OWNER:-}"
+PROTECTED_PREFIX="${PROTECTED_TAG_PREFIX:-latest}"
+PROTECTED_CONTAINS="${PROTECTED_TAG_CONTAINS:-buildcache}"
+
+case "$KEEP_MIN" in
+  *[!0-9]* | '')
+    echo "ghcr-package-retention: KEEP_MIN must be a non-negative integer" >&2
+    exit 2
+    ;;
+esac
+
+case "$OWNER_TYPE" in
+  user) package_root="user/packages/container" ;;
+  org)
+    [ -n "$OWNER" ] || {
+      echo "ghcr-package-retention: GHCR_OWNER is required when GHCR_OWNER_TYPE=org" >&2
+      exit 2
+    }
+    package_root="orgs/${OWNER}/packages/container"
+    ;;
+  *)
+    echo "ghcr-package-retention: GHCR_OWNER_TYPE must be user or org" >&2
+    exit 2
+    ;;
+esac
+
+if [ "$#" -eq 0 ]; then
+  echo "usage: ghcr-package-retention.sh <url-encoded-package>..." >&2
+  exit 2
+fi
+
+for pkg in "$@"; do
+  echo "=== Processing $pkg ==="
+  count=0
+  while IFS= read -r version_json; do
+    version_id=$(printf '%s' "$version_json" | jq -r '.id')
+    tags=$(printf '%s' "$version_json" | jq -r '[.metadata.container.tags[]?]')
+
+    protected=$(printf '%s' "$tags" |
+      jq --arg prefix "$PROTECTED_PREFIX" --arg contains "$PROTECTED_CONTAINS" \
+        'map(select(startswith($prefix) or contains($contains))) | length')
+    if [ "$protected" -gt 0 ]; then
+      printf '  keep (protected tag): version %s\n' "$version_id"
+      continue
+    fi
+
+    count=$((count + 1))
+    if [ "$count" -le "$KEEP_MIN" ]; then
+      printf '  keep (recent %d/%d): version %s\n' "$count" "$KEEP_MIN" "$version_id"
+      continue
+    fi
+
+    printf '  delete: version %s\n' "$version_id"
+    gh api -X DELETE "${package_root}/$pkg/versions/$version_id" || true
+  done < <(gh api \
+    "${package_root}/$pkg/versions?per_page=100" \
+    --jq '.[] | @json')
+done