Sync pgxntool to 2.2.0

pgxntool/CLAUDE.md

@@ -101,7 +101,7 @@ include pgxntool/base.mk
   - `PGXNVERSION` - version number
   - `EXTENSIONS` - list of extensions provided
   - `EXTENSION_*_VERSION` - per-extension versions
-  - `EXTENSION_VERSION_FILES` - auto-generated versioned SQL files
+  - `EXTENSION__CURRENT_VERSION__FILES` - the current/most-recent auto-generated versioned SQL file for each extension (not all version files)
 - `base.mk` includes `meta.mk` via `-include`
 
 ### The Magic of base.mk
@@ -144,11 +144,11 @@ make                    # Build extension (generates versioned SQL, docs)
 make test              # Full test: testdeps → install → installcheck → show diffs
 make results           # Run tests and update expected output files
 make html              # Generate HTML from Asciidoc sources
-make tag               # Create git branch for current META.json version
+make tag               # Create git tag for current META.json version
 make dist              # Create PGXN .zip (auto-tags, places in ../)
 make pgtle             # Generate pg_tle registration SQL (see pg_tle Support below)
 make check-pgtle       # Check pg_tle installation and report version
-make install-pgtle    # Install pg_tle registration SQL files into database
+make run-pgtle         # Register extensions with pg_tle in the database
 make pgxntool-sync     # Update to latest pgxntool via git subtree pull
 ```
 
@@ -204,7 +204,7 @@ When tests fail, examine the diff output carefully. The actual test output in `t
 
 ### Distribution Packaging
 - `make dist` creates `../PGXN-VERSION.zip`
-- Always creates git branch tag matching version
+- Always creates git tag matching version
 - Uses `git archive` to package
 - Validates repo is clean before tagging
 
@@ -227,16 +227,16 @@ pgxntool can generate pg_tle (Trusted Language Extensions) registration SQL for
 
 **Installation targets:**
 
-- `make check-pgtle` - Checks if pg_tle is installed and reports the version. Reports version from `pg_extension` if extension has been created, or newest available version from `pg_available_extension_versions` if available but not created. Errors if pg_tle not available in cluster. Assumes `PG*` environment variables are configured.
+- `make check-pgtle` - Checks if pg_tle is installed and reports the version. Reports the version from `pg_extension` if `CREATE EXTENSION pg_tle` has been run in the database. Errors if pg_tle is not available in the cluster. Assumes `PG*` environment variables are configured.
 
-- `make install-pgtle` - Auto-detects pg_tle version and installs appropriate registration SQL files. Updates or creates pg_tle extension as needed. Determines which version range files to install based on detected version. Runs all generated SQL files via `psql` to register extensions with pg_tle. Assumes `PG*` environment variables are configured.
+- `make run-pgtle` - Registers all extensions with pg_tle by executing the generated pg_tle registration SQL files. Requires pg_tle to already be installed in the target database (`CREATE EXTENSION pg_tle;`) -- it does not create the extension itself, and errors out telling you to run `make check-pgtle` if it's missing. Depends on `pgtle`, so it generates the SQL files first if needed. Assumes `PG*` environment variables are configured.
 
 **Version notation:**
 - `X.Y.Z+` means >= X.Y.Z
 - `X.Y.Z-A.B.C` means >= X.Y.Z and < A.B.C (note boundary)
 
 **Key implementation details:**
-- Script: `pgxntool/pgtle-wrap.sh` (bash)
+- Script: `pgxntool/pgtle.sh` (bash)
 - Parses `.control` files for metadata (NOT META.json)
 - Fixed delimiter: `$_pgtle_wrap_delimiter_$` (validated not in source)
 - Each output file contains ALL versions and ALL upgrade paths
@@ -269,6 +269,7 @@ Generated files depend on:
 4. **Control File Versions**: No automatic validation that `.control` matches `META.json` version
 5. **PGXNTOOL_NO_PGXS_INCLUDE**: Setting this skips PGXS inclusion (for special scenarios)
 6. **Distribution Placement**: `.zip` files go in parent directory (`../`) to avoid repo clutter
+7. **Never hand-edit an old versioned SQL file**: `sql/{ext}--{version}.sql` is only auto-regenerated by `make` for the extension's *current* `default_version` (from its `.control` file — not `META.json`; see "PGXN Distributions vs. Extensions" in README.asc). Every other `sql/{ext}--{version}.sql` (any version that is no longer current) is a frozen historical record used to test update paths and PostgreSQL-version compatibility — editing one directly silently corrupts that record. If you need to change something after a version has shipped, bump the version and add a `sql/{ext}--{old}--{new}.sql` upgrade script instead; never edit `sql/{ext}--{old}.sql` in place. This applies even though the file carries a generic `DO NOT EDIT - AUTO-GENERATED FILE` header — that header doesn't distinguish "regenerated every build" (current version) from "generated once, now frozen" (every other version). See "Version-Specific SQL Files" in README.asc for the full reasoning, including when it's acceptable to not commit a given version's file at all, and why that should be a plain `rm` rather than a `.gitignore` entry.
 
 ## Scripts
 

pgxntool/HISTORY.asc

@@ -1,3 +1,55 @@
+2.2.0
+-----
+== Add `check-stale-expected` to catch orphaned test/expected files
+`make test` now fails if `test/expected/*.out` (or `test/build/expected/*.out`)
+has no corresponding `test/sql/*.sql` (or `test/build/*.sql`). If your project
+has genuinely stale expected-output files sitting around, `make test` will
+newly fail until they're removed. pg_regress's alternate expected-output
+files (`test_0.out` .. `test_9.out`) are recognized and not flagged as stale.
+
+== Rename `EXTENSION_VERSION_FILES` to `EXTENSION__CURRENT_VERSION__FILES`
+The old name implied it listed every version file for an extension; it
+actually only ever holds the current/most-recent one per extension. If your
+Makefile references `EXTENSION_VERSION_FILES` directly (e.g. to add extra
+dependencies to `DATA`), update it to `EXTENSION__CURRENT_VERSION__FILES`.
+
+== Add `make pgxntool-version` to print the embedded pgxntool version
+There was no way to tell which pgxntool version a project had embedded via
+`git subtree` short of digging through git history. `make pgxntool-version`
+(and `pgxntool/bin/version` directly) now prints it, read from the
+first line of `pgxntool/HISTORY.asc` -- the same line the release process
+stamps with the version number. The line is rejected unless it's `STABLE`
+or a plain `X.Y.Z` version (digits only, no pre-release suffixes).
+
+== Add `PGXN_REMOTE` to override the remote used by tag/rmtag/forcetag/dist
+These targets hardcoded the `origin` remote, silently re-tagging the wrong
+repository for maintainers whose `origin` is a personal fork. Defaults to
+`origin`, so existing behavior is unchanged unless you set it.
+
+== Fix `make pgtle PGTLE_VERSION=X` generating all versions instead of one
+`base.mk`'s `pgtle` target never passed the `PGTLE_VERSION` make variable
+through to `pgtle.sh --pgtle-version`, so it silently generated all pg_tle
+version ranges regardless of the value given on the command line.
+
+== Fix `pgtle.sh` rejecting non-numeric version aliases like `stable`
+`extract_version_from_filename()` required every version segment to start
+with a digit, so extensions using a persistent `stable` pseudo-version
+(`default_version = 'stable'`) failed with "Cannot parse version from
+filename". Widened to accept any non-empty, `--`-free version string,
+matching how pg_tle itself treats extension versions.
+
+== Fix versioned SQL file corruption under overlapping make invocations
+The rule generating `sql/<ext>--<version>.sql` used a `>` truncate followed
+by a separate `>>` append, so a rule that fired more than once (e.g.
+overlapping `make` processes) doubled the file's content. Now uses a single
+atomic redirect.
+
+== Add include guard to base.mk
+`base.mk` could end up included twice in one `make` run (for example, an
+extension's own `.mk` module includes it in addition to the Makefile's own
+include), which redefined every target and printed overriding-recipe
+warnings. A second inclusion is now a harmless no-op.
+
 2.1.0
 -----
 == Fix setup.sh / pgxntool-sync.sh / update-setup-files.sh inside a git worktree