chore: sync extension version metadata (#45)

Generate the extension version from package.json for trace metadata and validate it during checks.

Document the release process updates for generated version metadata.

Author: AbhiPrasad

AGENTS.md

@@ -28,6 +28,7 @@ When working in this repo, optimize for:
 - This repo is managed by [mise](https://mise.jdx.dev/) using `.tool-versions`; prefer that as the toolchain source of truth.
 - Preserve package identity in `package.json` as a pi package.
 - Keep the extension entrypoint at `src/index.ts` unless there is a strong reason to change it.
+- Keep `src/version.ts` generated from `package.json`; do not edit it by hand. After a package version bump, run `pnpm run sync:version` and commit the generated change.
 - Prefer evolving the current design over rewriting it.
 - Tracing must be best-effort: log failures and continue.
 - Preserve the intended trace hierarchy unless there is a strong reason to change it:
@@ -73,9 +74,11 @@ If the change affects extension lifecycle behavior, session persistence/restore,
 pnpm run test:integration
 ```
 
-If packaging changes were made, also run:
+If packaging changes or release version bumps were made, also run:
 
 ```bash
+pnpm run sync:version
+pnpm run check
 pnpm run pack
 pnpm pack --dry-run
 ```

CONTRIBUTING.md

@@ -32,6 +32,7 @@ This repo is managed by [mise](https://mise.jdx.dev/). Use the pinned project to
 ```bash
 mise install
 pnpm install
+pnpm run sync:version
 pnpm run check
 pnpm run pack
 pnpm run smoke
@@ -49,7 +50,8 @@ pnpm run smoke
 
 Notes:
 
-- `pnpm run check` is the main formatting, linting, and type-check entrypoint.
+- `pnpm run sync:version` regenerates `src/version.ts` from `package.json` after a version bump.
+- `pnpm run check` verifies `src/version.ts` is in sync, then runs the main formatting, linting, and type-check entrypoint.
 - `pnpm run typecheck` delegates to `vp check`.
 - `pnpm run pack` builds an optional library bundle in `dist/`.
 - pi loads the extension directly from `src/index.ts`, so local development does not require a build step.
@@ -77,6 +79,9 @@ Notes:
   - content normalization, truncation, IDs, small helpers
 - `src/types.ts`
   - shared TypeScript types for config, spans, state, and normalized messages
+- `src/version.ts`
+  - generated extension version constant derived from `package.json`
+  - do not edit by hand; run `pnpm run sync:version` after changing the package version
 
 ## Repo conventions
 
@@ -87,6 +92,7 @@ Notes:
 - Prefer Node built-ins over adding packages.
 - This repo uses **Vite+** for checks and packaging.
 - pi loads the extension directly from TypeScript; no build output directory is required for local development.
+- `src/version.ts` is generated at package/build time from `package.json`; `prepack` regenerates it and `check` fails if it is stale.
 
 ### Style
 
@@ -174,9 +180,11 @@ pnpm test
 pnpm run smoke
 ```
 
-If packaging changes were made, also run:
+If packaging changes or release version bumps were made, also run:
 
 ```bash
+pnpm run sync:version
+pnpm run check
 pnpm run pack
 pnpm pack --dry-run
 ```

docs/PUBLISHING.md

@@ -24,17 +24,20 @@ Before using the workflow, make sure:
 1. The package name on npm is correct: `@braintrust/pi-extension`
 2. npm trusted publishing is configured for this repository/package
 3. You have bumped `package.json` to the version you want to release
-4. The branch you want to publish is pushed to GitHub
+4. You have regenerated and committed `src/version.ts` with `pnpm run sync:version`
+5. The branch you want to publish is pushed to GitHub
 
 ## Release steps
 
 1. Update `package.json` with the target version.
-2. Commit and push the version bump to the branch you want to release from.
-3. In GitHub, open **Actions**.
-4. Run the **Publish package** workflow.
-5. Enter the branch to publish from, such as `main`.
-6. Start the workflow.
-7. After it succeeds, verify:
+2. Run `pnpm run sync:version` to regenerate `src/version.ts`.
+3. Run the local preflight checks below.
+4. Commit and push the version bump, including `src/version.ts`, to the branch you want to release from.
+5. In GitHub, open **Actions**.
+6. Run the **Publish package** workflow.
+7. Enter the branch to publish from, such as `main`.
+8. Start the workflow.
+9. After it succeeds, verify:
    - the package version exists on npm
    - the provenance attestation is present on npm
    - the `pi-extension-v<version>` tag was pushed
@@ -73,9 +76,9 @@ This job:
 - sets up pnpm and Node.js with npm registry access using those pinned versions
 - runs `pnpm install --frozen-lockfile`
 - runs validation and packaging commands:
-  - `pnpm run check`
+  - `pnpm run check` (including generated version sync validation)
   - `pnpm test`
-  - `pnpm run pack`
+  - `pnpm run pack` (regenerates `src/version.ts` via `prepack`)
   - `pnpm pack --dry-run`
   - `pnpm run smoke`
 - publishes to npm with provenance:
@@ -117,7 +120,7 @@ Example for version `0.1.0`:
 The workflow will fail if:
 
 - the target git tag already exists on the remote
-- formatting, linting, type checking, tests, pack, or smoke checks fail
+- generated version sync, formatting, linting, type checking, tests, pack, or smoke checks fail
 - npm trusted publishing is not configured correctly
 - npm rejects the publish for version or package metadata reasons
 
@@ -131,6 +134,7 @@ Important behavior:
 Before triggering a release, it is a good idea to run:
 
 ```bash
+pnpm run sync:version
 pnpm run check
 pnpm test
 pnpm run pack
@@ -142,4 +146,5 @@ pnpm run smoke
 
 - The package is public, and `package.json` includes `publishConfig.access = "public"`.
 - The workflow is manual (`workflow_dispatch`) rather than tag-triggered.
-- If the release process changes, update both this file and `.github/workflows/publish.yml`.
+- `src/version.ts` is generated from `package.json` so trace metadata reports the package version without runtime package metadata loading.
+- If the release process changes, update this file, `AGENTS.md`, `CONTRIBUTING.md`, and `.github/workflows/publish.yml` as needed.

package.json

@@ -25,10 +25,12 @@
   },
   "scripts": {
     "preinstall": "node -e \"const userAgent = process.env.npm_config_user_agent || ''; if (process.env.INIT_CWD === process.cwd() && !userAgent.includes('pnpm/')) { console.error('Use pnpm in this repo.'); process.exit(1); }\"",
-    "check": "vp check",
+    "check": "node scripts/sync-version.mjs --check && vp check",
     "fmt": "vp fmt",
     "lint": "vp lint",
+    "prepack": "node scripts/sync-version.mjs",
     "pack": "vp pack",
+    "sync:version": "node scripts/sync-version.mjs",
     "test": "vitest run",
     "test:integration": "vitest run src/index.integration.test.ts",
     "test:watch": "vitest",

scripts/sync-version.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+
+const check = process.argv.includes("--check");
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const version = packageJson.version;
+
+if (typeof version !== "string" || version.length === 0) {
+  throw new Error("package.json version must be a non-empty string");
+}
+
+const target = new URL("../src/version.ts", import.meta.url);
+const content = `// This file is generated by scripts/sync-version.mjs. Do not edit by hand.\nexport const EXTENSION_VERSION = ${JSON.stringify(version)};\n`;
+
+if (check) {
+  const current = readFileSync(target, "utf8");
+  if (current !== content) {
+    console.error("src/version.ts is out of sync with package.json. Run `pnpm run sync:version`.");
+    process.exit(1);
+  }
+} else {
+  writeFileSync(target, content);
+}

src/index.test.ts

@@ -1,5 +1,9 @@
+import { readFileSync } from "node:fs";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
+const packageVersion = (JSON.parse(readFileSync("package.json", "utf8")) as { version: string })
+  .version;
+
 const mockState = vi.hoisted(() => ({
   startSpans: [] as Array<Record<string, unknown>>,
   logSpans: [] as Array<Record<string, unknown>>,
@@ -193,6 +197,7 @@ describe("braintrustPiExtension", () => {
     expect(mockState.widgets.at(-1)?.content?.[1]).toBe(
       "braintrust.dev/app/test-org/p/pi/logs?oid=trace-row-1",
     );
+    expect(mockState.startSpans[0]?.metadata).toMatchObject({ extension_version: packageVersion });
 
     await emit("session_shutdown");
 

src/index.ts

@@ -1,5 +1,5 @@
-import { basename, resolve } from "node:path";
 import { hostname, userInfo } from "node:os";
+import { basename, resolve } from "node:path";
 import type { AgentEndEvent, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { BraintrustClient, type BraintrustSpanHandle } from "./client.ts";
 import { createLogger, loadConfig } from "./config.ts";
@@ -13,6 +13,7 @@ import type {
   NormalizedAssistantMessage,
   TraceConfig,
 } from "./types.ts";
+import { EXTENSION_VERSION } from "./version.ts";
 import {
   buildTurnInput,
   extractErrorText,
@@ -29,7 +30,6 @@ import {
   toUnixSeconds,
 } from "./utils.ts";
 
-const EXTENSION_VERSION = "0.1.0";
 const TRACING_STATUS_KEY = "braintrust-tracing";
 const TRACING_WIDGET_KEY = "braintrust-trace-link";
 

src/version.ts

@@ -0,0 +1,2 @@
+// This file is generated by scripts/sync-version.mjs. Do not edit by hand.
+export const EXTENSION_VERSION = "0.5.0";