Files
PaperClipAI/.github/scripts/check-lockfile-release-age.mjs
T
Nicky LeachandPaperclip 3c32b8d4dc fix(ci): waive lockfile bake time for pinned harnesses (#22349)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner ships pinned harnesses that run those agents.
> - Some new models require a new harness release before they can run.
> - The lockfile bot waits three days before it can merge new dependency
versions automatically.
> - That wait held the Claude and Codex refresh in #22231.
> - This PR waives the wait for a fixed set of harness packages so model
updates can ship as soon as npm confirms the releases.

## Linked Issues or Issue Description

Refs #22231, #22278, #14942, #15572, and #18238.

**What happened?**

The refresh in #22231 held 16 new Claude Agent SDK and Codex versions
even though the new model support needed those harness updates.

**Expected behavior**

Verified npm releases of named harness packages can pass the gate
immediately. The gate applies the normal minimum age to other packages.

**Steps to reproduce**

Compare the parent and head of #22231 across the three lockfiles managed
by the bot. Run the gate with the publish times in its hold comment and
a clock within three days of the releases.

## What Changed

- Exempt 28 exact package names from the minimum age. These cover the
Claude Agent SDK, Codex CLI, their provider-specific ACP bridges,
OpenCode, and the Copilot binaries pinned by Runner.
- Take package identities from the Runner manifest and active provider
profiles, then check the managed lockfiles for platform binaries. Codex
platform aliases use the same registry name with a platform suffix on
each version. Pi and Kimi use separate npm locks. Gemini, Grok, the
local Cursor CLI, and Antigravity use separate install paths. The Cursor
Cloud SDK gets model availability from the service.
- Keep the npm publish-time and resolution checks for every entry.
Update the bot report and setup documentation.

## Verification

- Replayed the exact #22231 lockfile diff using the bot's recorded
publish times and a fixed clock. The previous gate held all 16 versions.
The new gate verified all 16 and held zero.
- Ran the workflow CLI against the same three lockfile pairs and the
live npm registry. It wrote `eligible=true` and reported 16 passing
versions.
- Reconciled the 28 exact names with the Runner manifest, provider
profiles, all three bot-managed pnpm lockfiles, and the npm manifests
for Claude Agent SDK 0.3.328, Codex 0.170.0, and OpenCode 1.18.34.
- Ran `node --test '.github/scripts/tests/*.test.mjs'` locally. All 810
tests passed. The new cases cover mixed refreshes, similar names,
registry errors, missing publish times, and non-registry resolutions.
- Ran `git diff --check`.
- GitHub Actions passed the required typecheck, build, test, and e2e
checks on `9c8bccac51`. The Canary runner shut down on the first
attempt, and browser shard 7 had a test-company cleanup error. Both
passed on the failed-jobs retry. [CI attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44610325309/attempts/2)
- Standard Greptile scored the same revision 5/5.
[Review](https://github.com/paperclipai/paperclip/pull/22349#issuecomment-7021573041)

## Risks

An npm release of an allowlisted harness can reach master during its
first three days through the existing automatic merge path. A
compromised release can use that same path. Every added version still
needs an npm publish time and a registry resolution. Review new platform
package names before adding them to the allowlist. Superagent requests
security review for this policy change. [Scanner
finding](https://github.com/paperclipai/paperclip/pull/22349#discussion_r4634801827)

## Model Used

OpenAI GPT-6 in Codex, with shell and code execution. The exact model
snapshot and context window were not reported.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-19 14:17:32 -08:00

204 lines
8.1 KiB
JavaScript

#!/usr/bin/env node
/**
* check-lockfile-release-age.mjs
* Decides whether the lockfile bot may merge refreshed pnpm lockfiles without review.
* Every added version must have a verified npm publish time. Versions outside
* the harness allowlist must also meet the minimum age.
*
* Exports: parseLockfilePackages(text), addedPackageVersions(baseText, headText),
* addedPackageVersionsAcross(pairs),
* checkReleaseAge(entries, { fetchPublishTime, now, minAgeMs, concurrency })
*
* CLI: node check-lockfile-release-age.mjs --base <file> --head <file> [--base <file> --head <file> ...]
* --min-age-days <n>
* Pass one --base/--head pair per lockfile, in the same order. Writes `eligible=true|false`
* to GITHUB_OUTPUT and a Markdown report to --report.
*/
import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { parseArgs } from 'node:util';
const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
// Every 2-space-indented line in `packages:` is an entry key. Keys can contain
// colons (URL and git dependencies), so match up to the final colon.
const PACKAGE_KEY = /^ {2}(\S.*):\s*$/;
const RESOLUTION = /^ {4}resolution: (.+?)\s*$/;
// A registry tarball is locked by integrity alone. A tarball URL, git repo or
// directory resolution names its own source and needs a human.
const REGISTRY_RESOLUTION = /^\{integrity: [^,{}]+\}$/;
const DAY_MS = 24 * 60 * 60 * 1000;
const HARNESS_PACKAGES = new Set([
'@agentclientprotocol/claude-agent-acp',
'@agentclientprotocol/codex-acp',
'@anthropic-ai/claude-agent-sdk',
'@anthropic-ai/claude-agent-sdk-darwin-arm64',
'@anthropic-ai/claude-agent-sdk-darwin-x64',
'@anthropic-ai/claude-agent-sdk-linux-arm64',
'@anthropic-ai/claude-agent-sdk-linux-arm64-musl',
'@anthropic-ai/claude-agent-sdk-linux-x64',
'@anthropic-ai/claude-agent-sdk-linux-x64-musl',
'@anthropic-ai/claude-agent-sdk-win32-arm64',
'@anthropic-ai/claude-agent-sdk-win32-x64',
'@github/copilot-darwin-arm64',
'@github/copilot-darwin-x64',
'@github/copilot-linux-x64',
'@openai/codex',
'opencode-ai',
'opencode-darwin-arm64',
'opencode-darwin-x64',
'opencode-darwin-x64-baseline',
'opencode-linux-arm64',
'opencode-linux-arm64-musl',
'opencode-linux-x64',
'opencode-linux-x64-baseline',
'opencode-linux-x64-baseline-musl',
'opencode-linux-x64-musl',
'opencode-windows-arm64',
'opencode-windows-x64',
'opencode-windows-x64-baseline',
]);
/** Maps each key of the lockfile's top-level `packages:` section to its resolution. */
export function parseLockfilePackages(text) {
const packages = new Map();
let inPackages = false;
let key = null;
for (const line of text.split('\n')) {
if (/^\S/.test(line)) {
inPackages = line.trimEnd() === 'packages:';
key = null;
continue;
}
if (!inPackages) continue;
const keyMatch = PACKAGE_KEY.exec(line);
if (keyMatch) {
key = keyMatch[1].replace(/^'(.*)'$/, '$1').replace(/\(.*$/, '');
packages.set(key, '');
continue;
}
const resolutionMatch = key && RESOLUTION.exec(line);
if (resolutionMatch) packages.set(key, resolutionMatch[1]);
}
return packages;
}
export function splitPackageKey(key) {
const at = key.lastIndexOf('@');
if (at <= 0) return { name: key, version: '' };
return { name: key.slice(0, at), version: key.slice(at + 1) };
}
/** Package entries in headText that baseText lacks or resolves differently. */
export function addedPackageVersions(baseText, headText) {
const base = parseLockfilePackages(baseText);
return [...parseLockfilePackages(headText)]
.filter(([key, resolution]) => base.get(key) !== resolution)
.sort(([a], [b]) => a.localeCompare(b))
.map(([key, resolution]) => ({ key, ...splitPackageKey(key), resolution }));
}
/** Added versions across several base/head lockfile pairs, each listed once. */
export function addedPackageVersionsAcross(pairs) {
const entries = new Map();
for (const [baseText, headText] of pairs) {
for (const entry of addedPackageVersions(baseText, headText)) entries.set(`${entry.key}\0${entry.resolution}`, entry);
}
return [...entries.values()].sort((a, b) => a.key.localeCompare(b.key));
}
export async function fetchNpmPublishTime(name, version, fetchImpl = fetch) {
const res = await fetchImpl(`https://registry.npmjs.org/${name.replace('/', '%2f')}`, {
headers: { Accept: 'application/json' },
signal: AbortSignal.timeout(30_000),
});
if (!res.ok) throw new Error(`npm registry returned ${res.status}`);
const doc = await res.json();
const published = doc.time?.[version];
return published ? new Date(published) : null;
}
/**
* Checks each added version. Fails closed: a lookup error, a missing publish time or a
* non-registry version holds the merge.
*/
export async function checkReleaseAge(entries, {
fetchPublishTime = fetchNpmPublishTime,
now = new Date(),
minAgeMs,
concurrency = 8,
}) {
const held = [];
const queue = [...entries];
const worker = async () => {
for (let entry = queue.shift(); entry; entry = queue.shift()) {
const reason = await holdReason(entry, fetchPublishTime, now, minAgeMs);
if (reason) held.push({ ...entry, reason });
}
};
await Promise.all(Array.from({ length: concurrency }, worker));
held.sort((a, b) => a.key.localeCompare(b.key));
return { eligible: held.length === 0, checked: entries.length, held };
}
async function holdReason({ name, version, resolution }, fetchPublishTime, now, minAgeMs) {
if (!SEMVER.test(version)) return 'not a registry version';
if (!REGISTRY_RESOLUTION.test(resolution ?? '')) return `not a registry resolution: ${resolution || 'missing'}`;
let published;
try {
published = await fetchPublishTime(name, version);
} catch (error) {
return `registry lookup failed: ${error.message}`;
}
if (!published || Number.isNaN(published.getTime())) return 'no publish time on npm';
const ageMs = now.getTime() - published.getTime();
if (ageMs < minAgeMs && !HARNESS_PACKAGES.has(name)) {
return `published ${published.toISOString()} (${(ageMs / DAY_MS).toFixed(1)} days ago)`;
}
return null;
}
export function formatReport(result, minAgeDays) {
const lines = ['<!-- lockfile-release-age -->'];
if (result.eligible) {
lines.push(`All ${result.checked} added package versions passed the release-age gate. The lockfile bot merges this PR.`);
} else {
lines.push(
`The lockfile bot did not merge this PR. These added package versions are newer than ${minAgeDays} days or could not be verified:`,
'',
...result.held.map(({ key, reason }) => `- \`${key}\`: ${reason}`),
'',
'A maintainer can review and merge this PR. If no one does, the daily refresh tries again and merges it once the refresh passes the gate.',
);
}
return `${lines.join('\n')}\n`;
}
async function main() {
const { values } = parseArgs({
options: {
base: { type: 'string', multiple: true },
head: { type: 'string', multiple: true },
'min-age-days': { type: 'string' },
report: { type: 'string' },
},
});
const minAgeDays = Number(values['min-age-days']);
const bases = values.base ?? [];
const heads = values.head ?? [];
if (bases.length === 0 || bases.length !== heads.length || !Number.isFinite(minAgeDays) || minAgeDays < 0) {
console.error('Usage: check-lockfile-release-age.mjs --base <file> --head <file> [--base <file> --head <file> ...] --min-age-days <n> [--report <file>]');
process.exit(2);
}
const entries = addedPackageVersionsAcross(bases.map((base, index) => [readFileSync(base, 'utf8'), readFileSync(heads[index], 'utf8')]));
const result = await checkReleaseAge(entries, { minAgeMs: minAgeDays * DAY_MS });
const report = formatReport(result, minAgeDays);
console.log(report);
if (values.report) writeFileSync(values.report, report);
if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `eligible=${result.eligible}\n`);
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
main().catch(e => { console.error(e.message); process.exit(1); });
}