tool(release): Sync SDK versions from .version

.github/actions/check-package-versions/action.yml

@@ -0,0 +1,29 @@
+name: Check package versions
+description: >
+  Test the version sync tool. Reject package version drift and a canonical
+  version that goes backward. Needs a prior checkout and python3 on PATH.
+
+runs:
+  using: composite
+  steps:
+    - name: Test version sync tool
+      shell: bash
+      run: python3 -m unittest discover -s scripts/tests -p 'test_*.py' -v
+
+    - name: Check package versions
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        # A shallow checkout hides the previous commit. Get one more commit, so
+        # a caller does not need a specific fetch-depth for the check below.
+        if ! git rev-parse --verify --quiet HEAD^ >/dev/null; then
+          git fetch --deepen=1 --quiet || true
+        fi
+
+        BASELINE=$(git show HEAD^:.version 2>/dev/null || true)
+        if [ -z "${BASELINE}" ]; then
+          echo "No previous .version; skipping the forward-only check."
+        fi
+
+        python3 scripts/sync_versions.py --check --not-below "${BASELINE}"

.github/workflows/publish.yml

@@ -15,8 +15,24 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  check-versions:
+    name: Check package versions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The version check compares .version against HEAD^.
+          fetch-depth: 2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: ./.github/actions/check-package-versions
+
   publish-typescript:
     name: Publish TypeScript SDK to npm
+    needs: check-versions
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -67,6 +83,7 @@ jobs:
 
   publish-python:
     name: Publish Python SDK to PyPI
+    needs: check-versions
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -132,6 +149,7 @@ jobs:
 
   publish-go:
     name: Publish Go SDK tag
+    needs: check-versions
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -140,12 +158,17 @@ jobs:
         with:
           fetch-depth: 0
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
       - name: Determine release tag
         id: tag
         run: |
-          VERSION=$(sed -nE 's/^[[:space:]]*PackageVersion[[:space:]]*=[[:space:]]*"([^"]+)".*$/\1/p' packages/code-storage-go/version.go | head -n 1)
+          set -euo pipefail
+          VERSION=$(python3 scripts/sync_versions.py --print)
           if [ -z "${VERSION}" ]; then
-            echo "Failed to extract PackageVersion from packages/code-storage-go/version.go" >&2
+            echo "Failed to read .version" >&2
             exit 1
           fi
           TAG="packages/code-storage-go/v${VERSION}"

.github/workflows/test.yml

@@ -11,6 +11,9 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - uses: actions/checkout@v4
+        with:
+          # The version check compares .version against HEAD^.
+          fetch-depth: 2
 
       - uses: actions/setup-node@v4
         with:
@@ -28,6 +31,8 @@ jobs:
         with:
           python-version: '3.12'
 
+      - uses: ./.github/actions/check-package-versions
+
       - run: pnpm install
         working-directory: packages/code-storage-typescript
 

.version

@@ -0,0 +1 @@
+1.16.2

AGENTS.md

@@ -24,6 +24,18 @@
   - `moon run code-storage-typescript:build`
   - `moon run git-storage-sdk-python:test`
   - `moon run git-storage-sdk-go:test`
+- Package versions (repo root):
+  - Edit only `.version` when you set a package version.
+  - Use `MAJOR.MINOR.PATCH`. npm, PyPI, and Go do not accept the same
+    prerelease and build metadata.
+  - Set a version above the previous version. CI rejects a version that goes
+    backward.
+  - `python3 scripts/sync_versions.py` sets all package versions from `.version`.
+  - `python3 scripts/sync_versions.py --check` detects version differences.
+  - `python3 scripts/sync_versions.py --print` reads the version for a release
+    tag. Use it instead of a second parser for `.version`.
+  - CI runs the check with `.github/actions/check-package-versions`. Reuse that
+    action in a new workflow.
 
 ## Coding Style & Naming Conventions
 - TypeScript: follow existing `src/` style; use `camelCase` variables and
@@ -38,6 +50,47 @@
 - Python: pytest; tests in `tests/test_*.py` with coverage options in
   `pyproject.toml`.
 - Go: `go test` across the module.
+- Version tool: `python3 -m unittest discover -s scripts/tests` runs the tests in
+  `scripts/tests/`.
+
+## TypeScript SDK Rules
+
+The `@pierre/storage` package is a public production SDK. Preserve semver
+compatibility and coordinate each breaking change.
+
+- The package supports ESM and CommonJS consumers.
+- The package supports Node and edge runtimes that provide `fetch`.
+- The package creates authenticated Git URLs and wraps repository REST APIs.
+- Consumers depend on the generated `dist` output.
+- `packages/code-storage-typescript/src/index.ts` is the public entry point.
+- `packages/code-storage-typescript/src/types.ts` defines the shared API types.
+- `packages/code-storage-typescript/tests/index.test.ts` covers the public API.
+- `packages/code-storage-typescript/tests/full-workflow.js` is the live smoke
+  test.
+- `packages/code-storage-typescript/tsup.config.ts` defines the API and storage
+  base URLs.
+- Keep the TypeScript types and README in sync with each request or response
+  change.
+- Avoid Node built-in imports that break browser use.
+- Keep the `resolveCommitTtlSeconds` default at one hour.
+- Use `DEFAULT_TOKEN_TTL_SECONDS` for that default.
+- Keep `Repo.restoreCommit` on `repos/restore-commit`. Do not add an automatic
+  fallback to the legacy endpoints.
+- Preserve the `RefUpdateError` status, reason, message, and ref fields.
+- Keep `Repo.createCommitFromDiff` on `repos/diff-commit`.
+- Keep its return type as `Promise<CommitResult>`.
+- Reuse the commit-pack error helpers in `Repo.createCommitFromDiff`.
+- Keep ES256 private-key authentication compatible with the README example.
+- Keep raw API payload names as `*Response`.
+- Keep camelCase consumer results as `*Result`.
+- Extend `normalizeDiffState` when the API adds a Git status.
+- Preserve `state` and `rawState` in normalized diff results.
+- Keep webhook push events typed and preserve `WebhookUnknownEvent`.
+- Convert commit timestamps to `Date` and preserve `rawDate`.
+- Route new commit sources through `toAsyncIterable` and `ensureUint8Array`.
+- Keep `CommitFileOptions.mode` restricted to `GitFileMode`.
+- Keep UTF-8 as the default text encoding.
+- Keep the Node `Buffer` fallback for non-UTF text encodings.
 
 ## Commit & Pull Request Guidelines
 - Git history shows short, informal subjects and no strict convention. Prefer
@@ -49,8 +102,6 @@
 ## Security & Configuration Notes
 - Never commit private keys or API tokens. Use local files or environment
   variables for SDK credentials.
-- Keep package-level docs (for example,
-  `packages/code-storage-typescript/AGENTS.md`) in sync with code changes.
 - Audit `skills/code-storage/SKILL.md` against the SDK packages whenever public
   API surface changes (endpoints, request/response shapes, JWT claims, scopes,
   policy ops, base-repo providers, exported constants/helpers). The skill

packages/code-storage-go/README.md

@@ -345,17 +345,6 @@ if err != nil {
 fmt.Println(repo.ID)
 ```
 
-## Releasing a new version
-
-Because this Go module lives in a monorepo, git tags must be prefixed with the module's subdirectory path:
-
-```bash
-git tag packages/code-storage-go/v0.8.0
-git push origin packages/code-storage-go/v0.8.0
-```
-
-Make sure the version in `version.go` (`PackageVersion`) matches the tag before tagging.
-
 ## Features
 
 - Create, list, find, and delete repositories.

packages/code-storage-go/version.go

@@ -1,8 +1,9 @@
 package storage
 
 const (
-	PackageName    = "code-storage-go-sdk"
-	PackageVersion = "1.16.1"
+	PackageName = "code-storage-go-sdk"
+	// PackageVersion is set from .version by scripts/sync_versions.py.
+	PackageVersion = "1.16.2"
 )
 
 func userAgent() string {

packages/code-storage-python/DEVELOPMENT.md

@@ -285,19 +285,6 @@ uv lock --upgrade-package httpx
 uv run pip-audit
 ```
 
-### Version bumping
-
-Update version in `pyproject.toml`:
-
-```toml
-[project]
-version = "0.2.0"
-```
-
-### Changelog
-
-Document changes in CHANGELOG.md following Keep a Changelog format.
-
 ## Resources
 
 - [Pierre API Documentation](https://docs.pierre.io/api)

packages/code-storage-python/PUBLISHING.md

@@ -254,24 +254,9 @@ twine upload --repository testpypi dist/*
 twine upload dist/*
 ```
 
-## Publishing Updates
+## Publish an Update
 
-When you release a new version:
-
-### 1. Update Version Number
-
-Edit `pyproject.toml`:
-
-```toml
-[project]
-version = "0.1.3"  # Increment version
-```
-
-### 2. Update CHANGELOG (if you have one)
-
-Document what changed.
-
-### 3. Build and Upload
+### Build and Upload
 
 ```bash
 # Clean old builds
@@ -290,20 +275,14 @@ twine check dist/*
 twine upload --repository testpypi dist/*
 
 # Test installation
-pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pierre-storage==0.1.3
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pierre-storage
 
 # If good, upload to PyPI
 twine upload dist/*
 ```
 
 ## Troubleshooting
 
-### Error: "File already exists"
-
-You can't re-upload the same version. You must increment the version number.
-
-**Solution**: Update version in `pyproject.toml`, rebuild, and upload.
-
 ### Error: "Invalid username or password"
 
 Common mistakes: