fix: Stop publishing package.json and inject the version instead

Seam\Utils\PackageVersion read package.json from the package root at
runtime to set the seam-sdk-version header, which forced a development
manifest into every published package.

Replace it with a VERSION constant, and inject that constant from
package.json in the version lifecycle script, which npm runs after the
bump but before the commit, so the value is part of the tagged commit.
Packagist publishes the tag with no build step in between, so unlike the
JavaScript SDK, which injects at pack time, the version has to be
committed before the tag, as the Ruby SDK does with lib/seam/version.rb.

Add export-ignore rules to .gitattributes so development files are kept
out of the archives Composer downloads as dist, which composer.json's
archive exclude list does not govern, and exclude package.json from
composer archive as well.

Cover the constant with tests asserting it matches package.json and is
what SeamClient sends, so a hand edit or a missed injection fails.

Removes Seam\Utils\PackageVersionException, which only signalled an
unreadable package.json and has no remaining purpose.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RFK47311nWtbd3gHmjdknR

Author: claude

.gitattributes

@@ -1,3 +1,25 @@
 src/Resources/*.php linguist-generated
 src/Routes/*.php linguist-generated
 src/SeamClient.php linguist-generated
+
+# Keep development files out of the published package.
+# GitHub builds the archives Composer downloads as dist with git archive,
+# which honours these rules.
+/.devcontainer export-ignore
+/.editorconfig export-ignore
+/.env.example export-ignore
+/.github export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.npmrc export-ignore
+/.prettierignore export-ignore
+/.prettierrc.json export-ignore
+/.releaserc.json export-ignore
+/codegen export-ignore
+/eslint.config.ts export-ignore
+/inject-version.ts export-ignore
+/package-lock.json export-ignore
+/package.json export-ignore
+/phpunit.xml.dist export-ignore
+/tests export-ignore
+/tsconfig.json export-ignore

README.md

@@ -234,15 +234,25 @@ and dispatches the [Version](.github/workflows/version.yml) workflow.
 Run the [Version](.github/workflows/version.yml) workflow with the
 version to cut.
 It runs `npm version`, which bumps the `version` field in `package.json`,
-creates a signed `v*` git tag and pushes it.
+injects that version into `Seam\Utils\PackageVersion`, creates a signed `v*`
+git tag and pushes it.
 Pushing the tag triggers the [Publish](.github/workflows/publish.yml)
 workflow, and [Packagist](https://packagist.org/packages/seamapi/seam)
 picks up the new tag from its GitHub webhook.
 
 > Composer has no canonical place to store a package version, since Packagist
-> derives it from the git tag.
-> This repository therefore keeps the version in `package.json` and lets
-> `npm version` manage the tag.
-> The SDK also reads that field at runtime via `Seam\Utils\PackageVersion`
-> to set its `seam-sdk-version` header, so `package.json` must remain in the
-> published package.
+> derives it from the git tag, and it publishes the tag as-is with no build
+> step in between.
+> This repository therefore keeps the version in `package.json`, which is a
+> development manifest that is not published, and injects it into the
+> `Seam\Utils\PackageVersion::VERSION` constant used for the
+> `seam-sdk-version` header.
+>
+> The injection runs from `inject-version.ts` in the `version` lifecycle
+> script, which npm runs after the bump but before the commit, so the updated
+> constant is part of the tagged commit.
+> Never edit that constant by hand; a test asserts it matches `package.json`.
+
+Development files are kept out of the published package with `export-ignore`
+rules in `.gitattributes`, which `git archive` honours when GitHub builds the
+archives Composer downloads as `dist`.

composer.json

@@ -69,7 +69,9 @@
       "/.prettierrc.json",
       "/.releaserc.json",
       "/eslint.config.ts",
+      "/inject-version.ts",
       "/package-lock.json",
+      "/package.json",
       "/phpunit.xml.dist",
       "/tsconfig.json"
     ]

inject-version.ts

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+const versionFile = './src/Utils/PackageVersion.php'
+
+const versionPattern = /public const VERSION = "[^"]*";/
+
+const main = async (): Promise<void> => {
+  const version = await injectVersion(
+    fileURLToPath(new URL(versionFile, import.meta.url)),
+  )
+  // eslint-disable-next-line no-console
+  console.log(`✓ Version ${version} injected into ${versionFile}`)
+}
+
+const injectVersion = async (path: string): Promise<string> => {
+  const { version } = await readPackageJson()
+
+  if (version == null) {
+    throw new Error('Missing version in package.json')
+  }
+
+  const data = (await readFile(path)).toString()
+
+  if (!versionPattern.test(data)) {
+    throw new Error(`Could not find the version constant in ${versionFile}`)
+  }
+
+  await writeFile(
+    path,
+    data.replace(versionPattern, `public const VERSION = "${version}";`),
+  )
+
+  return version
+}
+
+const readPackageJson = async (): Promise<{ version?: string }> => {
+  const pkgBuff = await readFile(
+    fileURLToPath(new URL('package.json', import.meta.url)),
+  )
+  return JSON.parse(pkgBuff.toString())
+}
+
+await main()

package.json

@@ -5,6 +5,7 @@
   "private": true,
   "license": "MIT",
   "scripts": {
+    "version": "tsx ./inject-version.ts && git add src/Utils/PackageVersion.php",
     "postversion": "git push --follow-tags",
     "generate": "tsx codegen/smith.ts",
     "postgenerate": "npm run format",

src/Utils/PackageVersion.php

@@ -2,41 +2,18 @@
 
 namespace Seam\Utils;
 
-class PackageVersionException extends \Exception {}
-
 class PackageVersion
 {
-    public static function get()
+    /**
+     * The version of this package.
+     *
+     * Injected from package.json when a version is cut, by the version
+     * lifecycle script in package.json. Do not edit by hand.
+     */
+    public const VERSION = "3.5.0";
+
+    public static function get(): string
     {
-        $filePath = __DIR__ . "/../../package.json";
-
-        if (!file_exists($filePath)) {
-            throw new PackageVersionException(
-                "Can't get package version. File package.json does not exist.",
-            );
-        }
-
-        $content = file_get_contents($filePath);
-        if ($content === false) {
-            throw new PackageVersionException(
-                "Unable to read package.json file to get package version.",
-            );
-        }
-
-        $json = json_decode($content, true);
-        if (json_last_error() !== JSON_ERROR_NONE) {
-            throw new PackageVersionException(
-                "JSON decode error occurred when decoding package.json: " .
-                    json_last_error_msg(),
-            );
-        }
-
-        if (!isset($json["version"])) {
-            throw new PackageVersionException(
-                "Version not set in package.json",
-            );
-        }
-
-        return $json["version"];
+        return self::VERSION;
     }
 }

tests/PackageVersionTest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+use Seam\Utils\PackageVersion;
+
+final class PackageVersionTest extends TestCase
+{
+    public function testVersionMatchesPackageJson(): void
+    {
+        $path = __DIR__ . "/../package.json";
+        $contents = file_get_contents($path);
+        $this->assertIsString($contents, "Could not read $path");
+
+        $package = json_decode($contents, true);
+        $this->assertIsArray($package, "Could not decode $path");
+        $this->assertArrayHasKey("version", $package);
+
+        $this->assertSame(
+            $package["version"],
+            PackageVersion::get(),
+            "Seam\\Utils\\PackageVersion is out of date with package.json. " .
+                "It is injected by the version lifecycle script when a " .
+                "version is cut and should not be edited by hand.",
+        );
+    }
+
+    public function testVersionIsUsedAsTheSdkVersionHeader(): void
+    {
+        $seam = new \Seam\SeamClient("seam_apikey1_token");
+        $headers = $seam->client->getConfig("headers");
+
+        $this->assertSame(PackageVersion::get(), $headers["seam-sdk-version"]);
+    }
+}

tsconfig.json

@@ -2,5 +2,5 @@
   "$schema": "https://json.schemastore.org/tsconfig.json",
   "extends": "./node_modules/@seamapi/smith/tsconfig.base.json",
   "files": ["codegen/index.ts"],
-  "include": ["codegen/**/*", "eslint.config.ts"]
+  "include": ["codegen/**/*", "eslint.config.ts", "inject-version.ts"]
 }