Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-27 02:44:50 +01:00
Code Issues Packages Projects Releases Wiki Activity
3,052 Commits 1,310 Branches 2,101 Tags
b2ac35effb660dd18fde35a0b8e8f56079a1273d
Commit Graph
3 Commits
Author SHA1 Message Date
DottaandPaperclip e0f1905222 [codex] Quiet packaged version fallback diagnostics (#9207) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The server startup path reports the product version from package
metadata and, in source checkouts, Git metadata.
> - Packaged installs can run from `node_modules`, where Git metadata is
normally unavailable and that absence is expected.
> - The fallback path was still attempting Git metadata probing in
packaged contexts, which could print scary diagnostic noise during
onboarding even though the package version fallback was working.
> - This pull request makes the packaged path skip Git probing only when
the package does not look like a source checkout, and keeps fallback
diagnostics opt-in.
> - The benefit is a quieter first-run experience without weakening
source-checkout version detection or debug diagnostics.

## Linked Issues or Issue Description

No public GitHub issue exists.

### Bug Report

#### Pre-submission checklist

- [x] I have searched existing open and closed issues and this is not a
duplicate.
- [x] I am on the latest released version of Paperclip or can reproduce
on `master`.
- [x] I have confirmed the error originates in Paperclip itself, not in
an agent adapter, API provider, or local configuration.

#### What happened?

When Paperclip starts from a packaged install, server version resolution
can fall back from Git metadata to package metadata. That expected
fallback path could emit scary Git diagnostic noise during onboarding
even though startup could continue normally.

#### Expected behavior

Packaged Paperclip startup should use package metadata quietly when Git
metadata is unavailable. Source checkouts should still use Git-derived
versions, and operators who explicitly opt into version-resolution
diagnostics should still receive useful Git failure details.

#### Steps to reproduce

1. Run Paperclip from a packaged install where the server package is
under `node_modules` and does not include package-local Git metadata.
2. Start the server in an environment where `git describe` cannot
resolve repository metadata for that package.
3. Observe that version fallback can produce Git diagnostic noise during
startup even though the package version fallback is expected.

#### Paperclip version or commit

Reproduced against the pre-fix server version resolution behavior on
`master`-derived builds.

#### Deployment mode

Self-hosted server / packaged local install.

#### Installation method

npm / pnpm package install.

#### Agent adapter(s) involved

Not adapter-specific; this is core server startup/version behavior.

#### Database mode

Not database-related.

#### Access context

Unclear / not applicable.

#### Relevant logs or output

Git fallback diagnostics from `git describe` could appear during
packaged startup. The exact path and Git output depend on the operator
environment.

#### Additional context

The fix keeps diagnostics available behind
`PAPERCLIP_DEBUG_VERSION_RESOLUTION=1` and preserves source-checkout Git
version detection, including source paths that happen to contain a
`node_modules` segment.

#### Privacy checklist

- [x] I have reviewed all pasted output for PII and redacted where
necessary.

## What Changed

- Skip Git metadata probing for packaged installs under `node_modules`
only when no package-local Git metadata is present.
- Preserve Git-derived version detection for source or linked workspace
checkouts, even when their path contains a `node_modules` segment.
- Keep fallback diagnostics behind the existing debug/diagnostic opt-in
path.
- Include useful Git failure details such as stderr/stdout/stack/cause
when diagnostics are enabled.
- Add version tests covering packaged fallback behavior, source-checkout
detection, richer diagnostics, and quiet default output.

## Verification

- `pnpm vitest run server/src/__tests__/version.test.ts` passed after
the Greptile follow-up changes.
- `pnpm --filter @paperclipai/server typecheck` passed.
- `git diff --check` passed.
- Greptile completed with confidence score 5/5 and no blocking issues on
the latest reviewed commit.

## Risks

Low risk. The change is scoped to version fallback behavior.
Source-checkout Git version detection remains covered, while packaged
`node_modules` contexts intentionally rely on package metadata instead
of Git probing.

> 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

OpenAI Codex, GPT-5-class coding agent with shell/tool use in the
Paperclip workspace.

## 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-07-10 19:31:36 -05:00
Nicky LeachandPaperclip 8516700217 fix(server): report source-install version from git metadata (#9103) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server reports its own version through `server/src/version.ts`,
which is read by the `/health` endpoint and the telemetry client
> - When running from a cloned source tree, `server/package.json` is
frozen at the last published release version (e.g. `0.3.1`), so the
reported `serverVersion` never reflects how far the local checkout has
drifted from that release
> - Operators and support staff cannot tell from telemetry or health
output whether they are running a tagged release or a development build
with local commits on top
> - A `git describe --tags --match v* --long --dirty` call at startup
gives the exact nearest tag, number of commits since it, the current
SHA, and whether the tree is dirty — all the information needed to
compute a semantically meaningful version
> - This pull request replaces the static `pkg.version` export with a
`resolveServerVersion()` call that parses `git describe` output into
`YYYY.MDD.P+N.git.<sha>` (drift), `YYYY.MDD.P` (clean on-tag), or
appends `.dirty` for a modified tree, with a non-throwing fallback to
`package.json` when git is unavailable
> - The benefit is that from-source installs now report a version string
that lets operators and support quickly identify their exact checkout
state without running additional git commands

## Linked Issues or Issue Description

No pre-existing public issue. Inline description:

**What happened?**

When Paperclip is installed from source (git clone + pnpm), `GET
/health` and the telemetry envelope report the version frozen at the
last published `package.json` value (e.g. `0.3.1`) regardless of how
many commits ahead of that tag the local checkout is.

**Expected behavior**

The reported version should reflect the actual local state — nearest
release tag, number of commits since that tag, abbreviated commit SHA,
and a dirty marker when the working tree has uncommitted changes.

**Steps to reproduce**

Clone the repo, run `pnpm install && pnpm --filter @paperclipai/server
start`, then call `GET /health` or inspect telemetry envelopes. The
`serverVersion` field shows the `package.json` version even when the
checkout is dozens of commits ahead of that tag.

**Paperclip version or commit**

Affects all source-tree installs where `package.json` has not been
updated to match the current HEAD.

**Deployment mode**

Source install (git clone).

## What Changed

- `server/src/version.ts`: extracted `resolveServerVersion()` (replaces
the module-level `const serverVersion`) and `parseGitDescribeVersion()`
(exported for unit testing); the default implementation shells out to
`git describe --tags --match v* --long --dirty` with a 1 500 ms timeout;
falls back to `pkg.version ?? "0.0.0"` without throwing when git is
unavailable or the output cannot be parsed; replaced `logger` import
with a `console.debug`-based default to avoid pulling pino transport
side effects into a zero-dependency utility module
- `server/src/__tests__/version.test.ts`: 7-test unit suite covering
drift, clean on-tag collapse, dirty on-tag edge case, unparseable
fallback, `resolveServerVersion` happy path, and git-unavailable
fallback — all exercised via injected stubs without spawning a real git
process

## Verification

```sh
# Unit tests (7 tests)
pnpm exec vitest run server/src/__tests__/version.test.ts

# Type check
pnpm --filter @paperclipai/server typecheck

# Health and telemetry regression
pnpm exec vitest run server/src/__tests__/health.test.ts server/src/__tests__/telemetry-client-flush.test.ts

# Runtime smoke (from-source checkout)
# git describe --tags --match 'v*' --long  =>  v2026.626.0-58-g518fc71ce
# server startup => serverVersion = 2026.626.0+59.git.3367571cc
```

All commands passed at the committed HEAD.

## Risks

Low. The change is additive and self-contained to
`server/src/version.ts`:

- `git describe` is called once at module load with a 1 500 ms timeout;
failure (non-git environment, git not on PATH, timeout) is silently
caught and falls back to `pkg.version`, preserving existing behavior for
published-package installs
- No API surface, database schema, or migration is touched
- The telemetry envelope already carried `serverVersion`; only the value
changes for source-tree installs

## Model Used

Claude Sonnet 4.6 (`claude-sonnet-4-6`) with tool use and code
execution. Context window: 200 k tokens.

## 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)
- [ ] 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
- [ ] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
 2026-07-06 09:15:44 -07:00
Sai Shankar 02bf0dd862 add app version label 2026-03-17 09:40:07 +05:30