mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The server reports which commit it runs. `GET /api/health` and `GET
/api/liveness` return it, and the board UI and the hosting control plane
poll these routes
> - The commit comes from `getServerInfoSnapshot()` in
`server/src/server-info.ts`. The health route calls it on each request.
The snapshot keeps its Git metadata for 3 seconds, then reads it again
with `execFileSync("git", ["show", ...])`, which is a synchronous child
process
> - A container or packaged install has the `git` command but no
checkout. There `git show` can only fail, and the server then uses the
commit that the build supplied. The failed start still stops the event
loop for the length of a process start
> - A CPU profile of a busy hosted server showed this cost on the main
thread
> - This pull request looks for a checkout before it starts `git`.
Without a checkout the server takes the build-commit path directly
> - The benefit is that health polls start no child process on a server
that does not run from a checkout, and the responses stay the same
## Linked Issues or Issue Description
No public issue exists. I searched open and closed pull requests for
`server-info git health`, `readGitInfo` and `getServerInfoSnapshot`.
Related merged work: #8753 added the 3 second refresh so that the debug
view follows a checkout, #10563 and #10566 added the build commit,
#18649 took the process start time off the Git probes. No open pull
request covers this change.
**What happened?**
`server/src/app.ts` creates the health routes without a `serverInfo`
option, so each `GET /api/health` request calls
`getServerInfoSnapshot()`. When the 3 second cache is expired, the call
starts `git show -s HEAD`. On an install without a checkout the command
fails each time, so the failure is paid again on each refresh. The rate
is one `git` start for each request when requests are 3 seconds or more
apart, and one start for each 3 seconds when requests are more frequent.
It is not one start for each request in a burst.
A 30 second CPU profile of the main thread of a hosted server (commit
1d153f62b6, Node 24, main thread at 93% of one core, process about 4 GB
resident) showed `getServerInfoSnapshot` → `readGitInfo` → the `git
show` command at 0.6% inclusive. That is about 190 ms in 32 seconds,
which agrees with one failed start for each 3 second refresh. The
profile showed only the `git show` command under `readGitInfo`, not the
status or branch commands that run after a successful `git show`. The
native child-process spawn was 0.9% self time in the full profile; other
callers also start processes.
**Expected behavior**
A server that does not run from a Git checkout starts no `git` process
for health or liveness requests. It reports the build commit, as before.
A server that runs from a checkout continues to read Git after each 3
second refresh, because the commit and the local changes of a checkout
can change while the process runs (#8753).
**Steps to reproduce**
1. Run `pnpm --filter @paperclipai/server exec tsx
scripts/benchmark-health-server-info.ts --requests=200` on the parent
commit. The benchmark puts a counting `git` wrapper first on `PATH`. The
wrapper records the start and then runs the real `git`.
2. Read the row `packaged install: no checkout, build supplies the
commit`, pattern `polled every 5000 ms`. It shows 200 `git` execs for
200 health requests, and 1 exec when the routes are created.
**Paperclip version or commit**
`master` at ef2b53b675. The profile is from 1d153f62b6.
**Deployment mode**
All modes. The profile is from an `authenticated` hosted server that
runs the container image. The image installs `git`, and the build
context excludes `.git` (`.dockerignore`).
**Node.js version**
Profile: Node 24. Local benchmark and tests: Node 26.4.0 on darwin
arm64.
## What Changed
- `server/src/server-info.ts`: the default `git show` command first
looks for a checkout. A checkout is a `.git` entry in the working
directory or in one of its parents, or a `GIT_DIR` value. Without one,
the command throws before it starts a process, and `readGitInfo` takes
its existing build-commit path. The same check applies when
`/api/liveness` reads the snapshot at route creation.
- The 3 second refresh, the checkout path, the injected-command path for
tests and `processStartedAt` are not changed.
- `server/src/__tests__/health-server-info-git-probe.test.ts` (new):
regression tests that count the `git` processes that the server starts.
The tests use real Git and real directories.
- `server/scripts/benchmark-health-server-info.ts` (new): the
reproduction and benchmark.
- No route file is changed. `server/src/routes/health.ts` continues to
read the snapshot on each request.
## Verification
Regression test, red then green:
- `cd server && pnpm exec vitest run
src/__tests__/health-server-info-git-probe.test.ts`
- Parent commit (with the test file of this branch): 1 of 4 tests fails.
`starts no git process when the server does not run from a checkout`
fails with `expected 6 to be +0`: one start when the routes are created
and one for each of 5 polls. The response assertions in that test pass
on the parent commit.
- This branch: 4 of 4 tests pass.
- The tests assert the number of `git` starts and the response content.
They do not assert time. The first test compares the full response text
of anonymous health, board health and liveness with the responses of a
server that has the snapshot injected. The other 3 tests pass on both
commits. They keep the checkout behavior: a new commit is visible after
the refresh, also from a subdirectory; a linked worktree (`.git` is a
file) is read; `GIT_DIR` is obeyed.
Benchmark, same machine, 200 health requests per row, 3 runs each
(ranges shown). Each row alternates anonymous and board requests against
routes that are created as `server/src/app.ts` creates them.
| Scenario | Request pattern | Before: `git` execs (route creation +
requests) | Before: ms per request | After: `git` execs | After: ms per
request |
| --- | --- | --- | --- | --- | --- |
| No checkout, build supplies the commit | polled each 5 s | 1 + 200 |
12.5 to 13.8 | 0 + 0 | 1.05 to 1.53 |
| No checkout, build supplies the commit | burst | 1 + 0 | 1.47 to 1.63
| 0 + 0 | 1.19 to 1.57 |
| Source checkout | polled each 5 s | 3 + 600 | 36.3 to 50.2 | 3 + 600 |
36.8 to 40.7 |
| Source checkout | burst | 3 + 0 | 1.38 to 1.40 | 3 + 0 | 1.03 to 1.45
|
- Command: `pnpm --filter @paperclipai/server exec tsx
scripts/benchmark-health-server-info.ts --requests=200`
- The `polled` pattern moves the clock that the server reads forward by
5 seconds before each request. It does not wait for real time.
- The benchmark prints a SHA-256 prefix of the anonymous health body, of
`serverInfo.git` in the board health body and of the liveness body. The
values are the same before and after in all rows.
- The `git` call is synchronous, so the difference per request (about 11
to 12 ms locally, which includes the shell wrapper) is time that the
event loop is blocked.
- The source checkout rows do not change. This is the intended result.
Assumption and evidence (`rules/runtime-dependency-boundaries.mdc`): the
change assumes that real Git fails where the check finds no checkout,
and that the check finds each checkout that Git finds. The first
regression test runs real `git show` in the same directory and asserts
that it fails. The other tests run real Git from a repository
subdirectory, from a linked worktree and with `GIT_DIR`. The new check
itself is a small number of `existsSync` calls (one for each directory
level) on each 3 second refresh.
Other checks:
- `cd server && pnpm exec vitest run src/__tests__/server-info.test.ts
src/__tests__/health.test.ts src/__tests__/liveness.test.ts
src/__tests__/health-dev-server-token.test.ts
src/__tests__/health-workspace-readiness.test.ts
src/__tests__/cloud-warm-standby.test.ts
src/services/native-runtime/native-controller-identity.test.ts` and the
new test file: 58 tests in 8 files pass.
- `tsc --noEmit` over the three changed TypeScript files: clean.
- `pnpm verify` exits 2 (broader verification required, because of the
new file in `server/scripts`). Required CI supplies that coverage.
- Not verified: the benchmark on Linux with a multi-gigabyte process,
and the hosted server after deploy. The local numbers come from a
process of about 700 MB, where a process start is cheaper than on the
profiled server. That the profiled server has no checkout is a
conclusion from the image build and from the profile; I did not read its
`serverInfo` response.
## Risks
- Low risk. The response bodies of `/api/health` and `/api/liveness` are
the same as before for an install without a checkout and for a checkout.
- Behavior shift: a server whose working directory is inside a bare
repository, with no `.git` entry and no `GIT_DIR`, reported the commit
of that repository before. It now reports the build commit, or no
commit. This layout is not a supported way to run the server.
- A server that runs from a source checkout continues to start up to 3
`git` processes on each 3 second refresh while health is polled. This
pull request does not change that path, because #8753 made it read the
checkout live on purpose.
- If a checkout is created around the working directory while the server
runs, the next refresh finds it, because the check runs on each refresh.
## Model Used
- Claude Fable 5.2 (Anthropic, model ID `claude-fable-5-2`), in Claude
Code with tool use (shell, file edits, GitHub CLI).
## 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
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
223 lines
6.2 KiB
TypeScript
223 lines
6.2 KiB
TypeScript
import { execFileSync } from "node:child_process";
|
|
import { existsSync } from "node:fs";
|
|
import { dirname, join } from "node:path";
|
|
import type { ServerGitInfo, ServerGitLocalChanges, ServerInfoSnapshot } from "@paperclipai/shared";
|
|
import { parseBuildCommit, readBuildCommit } from "./build-commit.js";
|
|
|
|
export type { ServerGitInfo, ServerInfoSnapshot };
|
|
|
|
type GitCommand = () => string;
|
|
type BuildCommitCommand = () => string | null;
|
|
|
|
const SHORT_SHA_RE = /^[0-9a-f]{7,40}$/i;
|
|
|
|
function workingDirectoryIsInsideGitCheckout(): boolean {
|
|
if (process.env.GIT_DIR) return true;
|
|
let directory = process.cwd();
|
|
for (;;) {
|
|
if (existsSync(join(directory, ".git"))) return true;
|
|
const parent = dirname(directory);
|
|
if (parent === directory) return false;
|
|
directory = parent;
|
|
}
|
|
}
|
|
|
|
function defaultGitCommand() {
|
|
if (!workingDirectoryIsInsideGitCheckout()) {
|
|
throw new Error("The working directory is not inside a Git checkout");
|
|
}
|
|
return execFileSync(
|
|
"git",
|
|
["show", "-s", "--format=%H%n%h%n%s%n%cI", "HEAD"],
|
|
{
|
|
encoding: "utf8",
|
|
stdio: ["ignore", "pipe", "ignore"],
|
|
timeout: 1500,
|
|
},
|
|
);
|
|
}
|
|
|
|
function defaultGitStatusCommand() {
|
|
return execFileSync(
|
|
"git",
|
|
["status", "--porcelain=v1", "--untracked-files=normal"],
|
|
{
|
|
encoding: "utf8",
|
|
stdio: ["ignore", "pipe", "ignore"],
|
|
timeout: 1500,
|
|
},
|
|
);
|
|
}
|
|
|
|
function defaultGitBranchCommand() {
|
|
return execFileSync(
|
|
"git",
|
|
["symbolic-ref", "--quiet", "--short", "HEAD"],
|
|
{
|
|
encoding: "utf8",
|
|
stdio: ["ignore", "pipe", "ignore"],
|
|
timeout: 1500,
|
|
},
|
|
);
|
|
}
|
|
|
|
function parseGitLocalChanges(output: string): ServerGitLocalChanges {
|
|
let stagedFileCount = 0;
|
|
let unstagedFileCount = 0;
|
|
let untrackedFileCount = 0;
|
|
|
|
for (const line of output.split(/\r?\n/)) {
|
|
if (!line) continue;
|
|
const indexStatus = line[0] ?? " ";
|
|
const worktreeStatus = line[1] ?? " ";
|
|
|
|
if (indexStatus === "?" && worktreeStatus === "?") {
|
|
untrackedFileCount += 1;
|
|
continue;
|
|
}
|
|
if (indexStatus !== " " && indexStatus !== "?") stagedFileCount += 1;
|
|
if (worktreeStatus !== " " && worktreeStatus !== "?") unstagedFileCount += 1;
|
|
}
|
|
|
|
return {
|
|
available: true,
|
|
hasLocalChanges: stagedFileCount + unstagedFileCount + untrackedFileCount > 0,
|
|
stagedFileCount,
|
|
unstagedFileCount,
|
|
untrackedFileCount,
|
|
};
|
|
}
|
|
|
|
function getGitLocalChanges(gitStatusCommand: GitCommand): ServerGitLocalChanges {
|
|
try {
|
|
return parseGitLocalChanges(gitStatusCommand());
|
|
} catch {
|
|
return { available: false, unavailableReason: "git_status_unavailable" };
|
|
}
|
|
}
|
|
|
|
function parseGitInfo(
|
|
output: string,
|
|
branchName: string | null,
|
|
localChanges: ServerGitLocalChanges,
|
|
): ServerGitInfo {
|
|
const [fullSha = "", shortSha = "", subject = "", committedAt = ""] = output
|
|
.trimEnd()
|
|
.split("\n");
|
|
const parsedFullSha = parseBuildCommit(fullSha);
|
|
const committedAtTime = Date.parse(committedAt);
|
|
|
|
if (!parsedFullSha || !SHORT_SHA_RE.test(shortSha)) {
|
|
return { available: false, unavailableReason: "invalid_git_metadata" };
|
|
}
|
|
|
|
return {
|
|
available: true,
|
|
fullSha: parsedFullSha,
|
|
shortSha,
|
|
branchName,
|
|
subject: subject.trim() || "No commit subject",
|
|
committedAt: Number.isNaN(committedAtTime) ? null : new Date(committedAtTime).toISOString(),
|
|
localChanges,
|
|
};
|
|
}
|
|
|
|
function readGitInfo(
|
|
gitCommand: GitCommand = defaultGitCommand,
|
|
gitStatusCommand: GitCommand = defaultGitStatusCommand,
|
|
gitBranchCommand: GitCommand = defaultGitBranchCommand,
|
|
buildCommitCommand: BuildCommitCommand = readBuildCommit,
|
|
): ServerGitInfo {
|
|
try {
|
|
const output = gitCommand();
|
|
const localChanges = getGitLocalChanges(gitStatusCommand);
|
|
let branchName: string | null = null;
|
|
try {
|
|
branchName = gitBranchCommand().trim() || null;
|
|
} catch {
|
|
branchName = null;
|
|
}
|
|
return parseGitInfo(output, branchName, localChanges);
|
|
} catch {
|
|
const buildCommit = parseBuildCommit(buildCommitCommand());
|
|
if (!buildCommit) {
|
|
return { available: false, unavailableReason: "git_unavailable" };
|
|
}
|
|
|
|
return {
|
|
available: true,
|
|
fullSha: buildCommit,
|
|
shortSha: buildCommit.slice(0, 7),
|
|
branchName: null,
|
|
subject: "Source build",
|
|
committedAt: null,
|
|
localChanges: {
|
|
available: false,
|
|
unavailableReason: "git_status_unavailable",
|
|
},
|
|
};
|
|
}
|
|
}
|
|
|
|
export function createServerInfoSnapshot(
|
|
opts: {
|
|
now?: Date;
|
|
gitCommand?: GitCommand;
|
|
gitStatusCommand?: GitCommand;
|
|
gitBranchCommand?: GitCommand;
|
|
buildCommitCommand?: BuildCommitCommand;
|
|
} = {},
|
|
): ServerInfoSnapshot {
|
|
return {
|
|
processStartedAt: (opts.now ?? new Date()).toISOString(),
|
|
git: readGitInfo(
|
|
opts.gitCommand,
|
|
opts.gitStatusCommand,
|
|
opts.gitBranchCommand,
|
|
opts.buildCommitCommand,
|
|
),
|
|
};
|
|
}
|
|
|
|
// processStartedAt is a true boot constant, but the running commit can change
|
|
// without the Node process restarting: a managed dev-server restart re-runs the
|
|
// code while keeping this module alive, so a commit captured once at boot goes
|
|
// stale. Re-read git HEAD on demand, throttled by a short TTL so frequent health
|
|
// polls don't spawn git on every request.
|
|
const GIT_INFO_CACHE_TTL_MS = 3000;
|
|
const processStartedAt = new Date().toISOString();
|
|
let gitInfoCache: { value: ServerGitInfo; expiresAt: number } | null = null;
|
|
|
|
// Lifecycle identity must not run the synchronous Git probes used by diagnostics.
|
|
export function getServerProcessStartedAt(): string {
|
|
return processStartedAt;
|
|
}
|
|
|
|
export function getServerInfoSnapshot(
|
|
opts: {
|
|
now?: number;
|
|
gitCommand?: GitCommand;
|
|
gitStatusCommand?: GitCommand;
|
|
gitBranchCommand?: GitCommand;
|
|
buildCommitCommand?: BuildCommitCommand;
|
|
} = {},
|
|
): ServerInfoSnapshot {
|
|
const now = opts.now ?? Date.now();
|
|
if (!gitInfoCache || now >= gitInfoCache.expiresAt) {
|
|
gitInfoCache = {
|
|
value: readGitInfo(
|
|
opts.gitCommand,
|
|
opts.gitStatusCommand,
|
|
opts.gitBranchCommand,
|
|
opts.buildCommitCommand,
|
|
),
|
|
expiresAt: now + GIT_INFO_CACHE_TTL_MS,
|
|
};
|
|
}
|
|
return { processStartedAt, git: gitInfoCache.value };
|
|
}
|
|
|
|
export function resetServerInfoCacheForTests(): void {
|
|
gitInfoCache = null;
|
|
}
|