mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Runner support suite proves the plugin SDK public types against
pinned source. The pins are in
`tests/runner-e2e/source-sdk-public-inputs.json`.
> - The pins cover every file in `packages/shared/src` and
`packages/plugins/sdk/src`, and the SDK build inputs (for example
`pnpm-lock.yaml`).
> - A PR that edits a pinned file and does not refresh the registry
fails three files in the "Runner support suite" lane.
> - Between 2026-11-12 10:27Z and 2026-11-13 01:14Z, this failure
occurred in 14 CI runs on 12 PRs.
> - The local check, `pnpm verify`, returned exit 2 ("let CI cover it")
for these changes. It did not mention the pins. Authors pushed, and CI
failed.
> - This pull request makes `pnpm verify` find stale pins before the
push. It also makes the opaque fixture error name the file and the fix.
> - The benefit is that authors find and fix the problem in seconds,
locally, instead of after a 6-minute CI lane.
## Linked Issues or Issue Description
**What happened?**
Three files in the "Runner support suite" lane failed together on many
unrelated PRs: `source-sdk-evidence.test.ts`,
`source-sdk-public-inputs.test.mjs` and
`source-sdk-public-type.test.ts`. Two of the three failed with the
opaque error `Reviewed SDK reference source changed`.
**Root cause**
The pins on master are not stale. The tests pass on master (58/58). Each
failing PR edited a pinned input and did not refresh the registry. I
compared the PR heads with their merge base:
- All 14 failing heads (12 PRs) changed a pinned input. None of them
changed `source-sdk-public-inputs.json`.
- All 19 heads in the same window that changed a pinned input and passed
this lane also refreshed the registry. This includes later heads of
three PRs that failed first (#21119, #21121, #21156).
- Two of the 12 PRs are Dependabot PRs that change only `pnpm-lock.yaml`
(#19593, #19594). The lockfile refresh bot already resyncs the pins for
lock changes on master.
**Steps to reproduce**
1. Start from `origin/master`.
2. Add one line to `packages/shared/src/types/heartbeat.ts` and commit
it.
3. Run `node node_modules/vitest/vitest.mjs run --config
tests/runner-e2e/vitest.config.ts source-sdk-evidence.test.ts
source-sdk-public-inputs.test.mjs source-sdk-public-type.test.ts`.
4. The result is the same as CI: 3 files fail, with the same 4 failures.
5. Run `pnpm verify --explain`. It returns exit 2 and does not mention
the pins.
**Expected behavior**
`pnpm verify` reports the stale pins and the refresh command before the
author pushes.
## What Changed
- `tests/runner-e2e/source-sdk-public-inputs.mjs`: add
`staleSdkPublicInputsInWorkingTree(root)`. It applies the existing drift
guard to the working tree (tracked and untracked files that git does not
ignore). Add `isSdkPublicInput(file)` and the shared failure message
`staleSdkPublicInputsMessage(stale)`. The committed-tree guard keeps its
behavior and now uses a shared comparison.
- `scripts/local-verify.mjs`: when the diff touches a pinned input, the
registry or `report-lock.json`, `pnpm verify` checks the pins first. If
they are stale, it exits 1 and prints the files and the refresh command.
The check reads files only. It does not write the registry.
- `tests/runner-e2e/source-sdk-reviewed-fixture.ts`: the error `Reviewed
SDK reference source changed` now names the file and gives the refresh
command.
- `tests/runner-e2e/source-sdk-public-inputs.test.mjs`: new test for the
working-tree guard (uncommitted edit, untracked file, ignored file). The
CI drift test uses the shared message.
- `doc/DEVELOPING.md`: document the new check under "Incremental local
verification".
No assertion is weakened. No pin is changed. No file under `.github/` is
changed.
## Verification
- Master, without this change: the three files pass (58/58).
- Red: on master plus a one-line edit to
`packages/shared/src/types/heartbeat.ts`, the three files fail with the
CI signature. `pnpm verify --explain` returns exit 2 and does not
mention the pins.
- With this change on the same red commit: `pnpm verify` exits 1 in
about 15 s and prints `tests/runner-e2e/source-sdk-public-inputs.json is
stale for 1 pinned input(s): packages/shared/src/types/heartbeat.ts
(changed). Commit your change, run ... --write, and commit the updated
registry.`
- Green: I followed the printed command (`node
tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD> --write`, then
commit). The three files then pass (59/59, with the new test).
- `node --test scripts/__tests__/local-verify.test.mjs`: 14/14 pass.
- `pnpm verify` on this branch returns exit 2 because
`scripts/local-verify.mjs` is a global CI input. Required CI supplies
the broad coverage.
## Risks
- Low risk. The new check only reads files. It runs only when the diff
touches a pinned input.
- `pnpm verify` now fails (exit 1) for a change that also fails in CI.
Before, it returned exit 2.
- The check needs a working `git ls-files` in the repository. `pnpm
verify` already needs git.
- Dependabot lock PRs still fail this lane until the lockfile bot
refreshes the pins. This PR does not change that path.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude (Anthropic), Claude Code agent with tool use (shell, git,
GitHub CLI). Commits are attributed to Claude Fable 5.2.
## 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
158 lines
12 KiB
JavaScript
158 lines
12 KiB
JavaScript
import { strict as assert } from "node:assert";
|
|
import { execFileSync } from "node:child_process";
|
|
import { createHash } from "node:crypto";
|
|
import { mkdir, mkdtemp, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
import { afterEach, test } from "vitest";
|
|
import { fileURLToPath } from "node:url";
|
|
import { isSdkPublicInput, staleSdkPublicInputs, staleSdkPublicInputsInWorkingTree, staleSdkPublicInputsMessage, synchronizeSdkPublicInputs } from "./source-sdk-public-inputs.mjs";
|
|
|
|
const registry = "tests/runner-e2e/source-sdk-public-inputs.json";
|
|
const reportLock = "tests/runner-e2e/report-lock.json";
|
|
const reportPolicy = (inputSha256, outputSha256) => `${JSON.stringify({ inputSha256, outputSha256, patchSha256: "0".repeat(64), basis: "synthetic" }, null, 2)}\n`;
|
|
const commit = (root, message) => { git(root, "add", "-A"); git(root, "-c", "user.name=Synthetic unit", "-c", "user.email=synthetic@example.invalid", "commit", "-qm", message); return git(root, "rev-parse", "HEAD").trim(); };
|
|
const roots = [];
|
|
const digest = bytes => createHash("sha256").update(bytes).digest("hex");
|
|
const blob = bytes => createHash("sha1").update(`blob ${Buffer.byteLength(bytes)}\0`).update(bytes).digest("hex");
|
|
const git = (root, ...args) => execFileSync("git", ["-c", "core.hooksPath=/dev/null", "-c", "commit.gpgsign=false", ...args], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
|
|
async function put(root, file, bytes) { await mkdir(path.dirname(path.join(root, file)), { recursive: true }); await writeFile(path.join(root, file), bytes); }
|
|
async function fixture() {
|
|
const root = await realpath(await mkdtemp(path.join(os.tmpdir(), "sdk-input-sync-"))); roots.push(root);
|
|
const files = ["package.json", "packages/plugins/sdk/package.json", "packages/plugins/sdk/tsconfig.json",
|
|
"packages/shared/package.json", "packages/shared/tsconfig.json", "pnpm-lock.yaml", "scripts/ensure-plugin-build-deps.mjs",
|
|
"tsconfig.base.json", "tsconfig.json", "packages/shared/src/schema.ts", "packages/plugins/sdk/src/types.ts"];
|
|
for (const file of files) await put(root, file, `synthetic original ${file}\n`);
|
|
const baseline = { inputs: Object.fromEntries(files.map(file => [file, blob(`synthetic stale ${file}\n`)])),
|
|
lockSha256: digest("synthetic authenticated restored lock"), compilerPackageSha256: "a".repeat(64),
|
|
parserPackageSha256: "b".repeat(64), parserEntrySha256: "c".repeat(64),
|
|
zodPackageSha256: "d".repeat(64), zodEntrySha256: "e".repeat(64), zodTypeFiles: { "index.d.cts": "f".repeat(64) } };
|
|
await put(root, registry, `${JSON.stringify(baseline, null, 2)}\n`);
|
|
// The reviewed report-lock policy: committed lock in, authenticated restored lock out.
|
|
await put(root, reportLock, reportPolicy(digest("synthetic original pnpm-lock.yaml\n"), baseline.lockSha256));
|
|
git(root, "init", "-q"); git(root, "add", ".");
|
|
git(root, "-c", "user.name=Synthetic unit", "-c", "user.email=synthetic@example.invalid", "commit", "-qm", "synthetic source");
|
|
return { root, baseline, revision: git(root, "rev-parse", "HEAD").trim() };
|
|
}
|
|
afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
|
|
|
|
test("synchronizes the committed source graph, preserves every runtime pin and is idempotent", async () => {
|
|
const { root, baseline } = await fixture();
|
|
await put(root, "packages/shared/src/added.ts", "synthetic added source\n");
|
|
git(root, "add", "."); git(root, "-c", "user.name=Synthetic unit", "-c", "user.email=synthetic@example.invalid", "commit", "-qm", "additional source");
|
|
const revision = git(root, "rev-parse", "HEAD").trim();
|
|
assert.equal((await synchronizeSdkPublicInputs(root, revision)).changed, true);
|
|
assert.deepEqual(JSON.parse(await readFile(path.join(root, registry), "utf8")), baseline, "check does not write");
|
|
const changed = await synchronizeSdkPublicInputs(root, revision, { write: true });
|
|
const updated = JSON.parse(await readFile(path.join(root, registry), "utf8"));
|
|
assert.equal(updated.inputs["packages/shared/src/added.ts"], blob("synthetic added source\n"));
|
|
for (const [file, pin] of Object.entries(updated.inputs)) assert.equal(pin, git(root, "rev-parse", `${revision}:${file}`).trim());
|
|
const { inputs: oldInputs, ...runtime } = baseline, { inputs: newInputs, ...afterRuntime } = updated;
|
|
assert.deepEqual(afterRuntime, runtime); assert.equal(changed.runtimePinsChanged, false);
|
|
assert.equal(changed.registrySha256, digest(await readFile(path.join(root, registry))));
|
|
assert.equal((await synchronizeSdkPublicInputs(root, revision)).changed, false);
|
|
});
|
|
for (const mutation of ["dirty", "missing", "extra", "symlink", "registry", "revision"]) {
|
|
test(`refuses ${mutation} source custody without writing the registry`, async () => {
|
|
const { root, revision } = await fixture();
|
|
const target = path.join(root, "packages/shared/src/schema.ts");
|
|
if (mutation === "dirty") await writeFile(target, "uncommitted synthetic source");
|
|
if (mutation === "missing") await rm(target);
|
|
if (mutation === "extra") await put(root, "packages/shared/src/uncommitted.ts", "uncommitted");
|
|
if (mutation === "symlink") { await rm(target); await symlink("../package.json", target); }
|
|
if (mutation === "registry") { const current = JSON.parse(await readFile(path.join(root, registry), "utf8")); current.parserEntrySha256 = "0".repeat(64); await writeFile(path.join(root, registry), JSON.stringify(current)); }
|
|
const before = await readFile(path.join(root, registry));
|
|
await assert.rejects(synchronizeSdkPublicInputs(root, mutation === "revision" ? "0".repeat(40) : revision, { write: true }));
|
|
assert.deepEqual(await readFile(path.join(root, registry)), before);
|
|
});
|
|
}
|
|
test("admits only the separately pinned restored lock overlay without changing its identities", async () => {
|
|
const { root, baseline, revision } = await fixture();
|
|
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic authenticated restored lock");
|
|
await synchronizeSdkPublicInputs(root, revision, { write: true });
|
|
const updated = JSON.parse(await readFile(path.join(root, registry), "utf8"));
|
|
assert.equal(updated.lockSha256, baseline.lockSha256);
|
|
assert.equal(updated.inputs["pnpm-lock.yaml"], git(root, "rev-parse", `${revision}:pnpm-lock.yaml`).trim());
|
|
await writeFile(path.join(root, "pnpm-lock.yaml"), "unknown lock overlay");
|
|
await assert.rejects(synchronizeSdkPublicInputs(root, revision));
|
|
});
|
|
|
|
// A lockfile refresh rewrites the lock and report-lock.json together (#20615).
|
|
// The sync carries the new reviewed output hash into lockSha256; nothing else.
|
|
test("a lockfile refresh moves lockSha256 to the committed reviewed report-lock output", async () => {
|
|
const { root, baseline, revision: first } = await fixture();
|
|
await synchronizeSdkPublicInputs(root, first, { write: true });
|
|
commit(root, "synced");
|
|
const refreshed = "synthetic refreshed pnpm-lock.yaml\n";
|
|
await put(root, "pnpm-lock.yaml", refreshed);
|
|
await put(root, reportLock, reportPolicy(baseline.lockSha256, digest(refreshed)));
|
|
const revision = commit(root, "lockfile refresh");
|
|
assert.deepEqual(await staleSdkPublicInputs(root), [
|
|
{ file: "pnpm-lock.yaml", change: "changed" },
|
|
{ file: `${reportLock} outputSha256`, change: "lockSha256 changed" },
|
|
]);
|
|
const result = await synchronizeSdkPublicInputs(root, revision, { write: true });
|
|
assert.equal(result.lockPinChanged, true); assert.equal(result.runtimePinsChanged, false);
|
|
const updated = JSON.parse(await readFile(path.join(root, registry), "utf8"));
|
|
assert.equal(updated.lockSha256, digest(refreshed));
|
|
assert.equal(updated.inputs["pnpm-lock.yaml"], blob(refreshed));
|
|
const { inputs: _old, lockSha256: _oldLock, ...runtime } = baseline, { inputs: _new, lockSha256: _newLock, ...afterRuntime } = updated;
|
|
assert.deepEqual(afterRuntime, runtime);
|
|
assert.deepEqual(await staleSdkPublicInputs(root), []);
|
|
});
|
|
test("refuses a committed lock that the report-lock policy does not review", async () => {
|
|
const { root } = await fixture();
|
|
await put(root, "pnpm-lock.yaml", "synthetic unreviewed lock\n");
|
|
const revision = commit(root, "unreviewed lock");
|
|
const before = await readFile(path.join(root, registry));
|
|
await assert.rejects(synchronizeSdkPublicInputs(root, revision, { write: true }), /not reviewed by tests\/runner-e2e\/report-lock\.json/);
|
|
assert.deepEqual(await readFile(path.join(root, registry)), before);
|
|
});
|
|
|
|
// The pins only prove the SDK public types while they match the committed
|
|
// source. A PR that edits packages/shared/src (or another pinned input) without
|
|
// refreshing them breaks every SDK-dependent Runner cell before its server
|
|
// starts, so fail here, cheaply, with the inputs and the fix command.
|
|
test("the committed SDK public source pins match this checkout's committed tree", async () => {
|
|
const root = fileURLToPath(new URL("../..", import.meta.url));
|
|
const stale = await staleSdkPublicInputs(root);
|
|
assert.deepEqual(stale, [], staleSdkPublicInputsMessage(stale));
|
|
});
|
|
// pnpm verify reads the working tree, so an uncommitted or unpushed edit to a
|
|
// pinned input is reported locally instead of failing the Runner support suite in CI.
|
|
test("the working-tree drift guard sees uncommitted and untracked pinned inputs", async () => {
|
|
const { root, revision } = await fixture();
|
|
await synchronizeSdkPublicInputs(root, revision, { write: true }); commit(root, "resync");
|
|
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), []);
|
|
await put(root, "packages/shared/src/schema.ts", "uncommitted synthetic edit\n");
|
|
await put(root, "packages/shared/src/untracked.ts", "untracked synthetic source\n");
|
|
await put(root, "packages/shared/src/ignored.ts", "ignored synthetic source\n"); await put(root, ".gitignore", "packages/shared/src/ignored.ts\n");
|
|
const stale = await staleSdkPublicInputsInWorkingTree(root);
|
|
assert.deepEqual(stale, [{ file: "packages/shared/src/schema.ts", change: "changed" }, { file: "packages/shared/src/untracked.ts", change: "unpinned" }]);
|
|
assert.match(staleSdkPublicInputsMessage(stale), /packages\/shared\/src\/schema\.ts \(changed\).*source-sdk-public-inputs\.mjs \$\(git rev-parse HEAD\) --write/);
|
|
assert.deepEqual(await staleSdkPublicInputs(root), [], "the committed-tree guard is unaffected by uncommitted edits");
|
|
git(root, "checkout", "--", "packages/shared/src/schema.ts");
|
|
await rm(path.join(root, "packages/shared/src/untracked.ts"));
|
|
// The reviewed restored lock overlay in the working tree is not drift; any other lock edit is.
|
|
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic authenticated restored lock");
|
|
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), []);
|
|
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic unreviewed lock edit\n");
|
|
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), [{ file: "pnpm-lock.yaml", change: "changed" }]);
|
|
// Committing the reviewed output lock without a registry refresh is drift: CI's committed-tree guard reports it, so must this one.
|
|
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic authenticated restored lock"); commit(root, "commit reviewed output lock");
|
|
assert.deepEqual(await staleSdkPublicInputs(root), [{ file: "pnpm-lock.yaml", change: "changed" }]);
|
|
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), [{ file: "pnpm-lock.yaml", change: "changed" }]);
|
|
assert.equal(isSdkPublicInput("packages/shared/src/types/heartbeat.ts"), true);
|
|
assert.equal(isSdkPublicInput("pnpm-lock.yaml"), true);
|
|
assert.equal(isSdkPublicInput("server/src/index.ts"), false);
|
|
});
|
|
test("the drift guard names changed, unpinned and removed inputs and clears after a resync", async () => {
|
|
const { root, revision } = await fixture();
|
|
assert.deepEqual((await staleSdkPublicInputs(root)).map(row => row.change), Array(11).fill("changed"));
|
|
await synchronizeSdkPublicInputs(root, revision, { write: true });
|
|
assert.deepEqual(await staleSdkPublicInputs(root), []);
|
|
await put(root, "packages/shared/src/added.ts", "synthetic added source\n"); await rm(path.join(root, "packages/plugins/sdk/src/types.ts"));
|
|
git(root, "add", "-A"); git(root, "-c", "user.name=Synthetic unit", "-c", "user.email=synthetic@example.invalid", "commit", "-qm", "drift");
|
|
assert.deepEqual(await staleSdkPublicInputs(root), [{ file: "packages/plugins/sdk/src/types.ts", change: "removed" }, { file: "packages/shared/src/added.ts", change: "unpinned" }]);
|
|
});
|