feat(packaging): include pglogical_create_subscriber in release packages

CLAUDE.md

@@ -155,3 +155,10 @@ git push origin v2.5.0-rc1
 - Windows: windows-2022, Chocolatey, Visual Studio 2022, WiX v5 for MSI
 
 **Artifacts:** Binary packages follow naming convention `pglogical-{version}-pg{pg_version}-{platform}-{arch}.{ext}`
+
+## Active Technologies
+- C (PostgreSQL extension), Bash (scripts), WiX v5 (Windows MSI), YAML (GitHub Actions) + WiX Toolset v5, GitHub Actions runners, pg_config (003-distribute-create-subscriber)
+- N/A (packaging feature, no data storage) (003-distribute-create-subscriber)
+
+## Recent Changes
+- 003-distribute-create-subscriber: Added C (PostgreSQL extension), Bash (scripts), WiX v5 (Windows MSI), YAML (GitHub Actions) + WiX Toolset v5, GitHub Actions runners, pg_config

packaging/unix/README.md

@@ -43,9 +43,10 @@ This is useful when pg_config is not available or you want to install to a speci
    - `PGDIR` environment variable (direct path to PostgreSQL installation)
    - `PG_CONFIG` environment variable (path to pg_config executable)
    - `pg_config` from PATH
-2. Copies shared libraries to `lib/` directory
-3. Copies extension files to `share/extension/` directory
-4. Uses sudo automatically if target directories require elevated permissions
+2. Copies executables to PostgreSQL `bin/` directory
+3. Copies shared libraries to `lib/` directory
+4. Copies extension files to `share/extension/` directory
+5. Uses sudo automatically if target directories require elevated permissions
 
 ## Package Contents
 
@@ -54,6 +55,8 @@ A typical package contains:
 ```
 pglogical-2.5.0-pg17-linux-x64/
 ├── install.sh                    # This installation script
+├── bin/
+│   └── pglogical_create_subscriber  # Subscriber creation utility
 ├── lib/
 │   ├── pglogical.so              # Main extension library
 │   └── pglogical_output.so       # Output plugin library
@@ -66,6 +69,20 @@ pglogical-2.5.0-pg17-linux-x64/
         └── pglogical_origin--1.0.0.sql
 ```
 
+## Bundled Utilities
+
+### pglogical_create_subscriber
+
+The `pglogical_create_subscriber` utility creates a new pglogical subscriber node from a physical base backup. This enables fast subscriber setup for large databases by combining physical backup with logical replication.
+
+**Usage:**
+```bash
+# After installation, verify the utility is available
+pglogical_create_subscriber --help
+```
+
+The utility is installed to the PostgreSQL bin directory alongside other PostgreSQL tools like `psql` and `pg_dump`.
+
 ## Post-Installation
 
 After installation, enable the extension in your database:

packaging/unix/install.sh

@@ -56,6 +56,7 @@ if [ -n "$PGDIR" ]; then
     info "Using PostgreSQL directory from PGDIR: $PGDIR"
 
     # Determine paths based on PGDIR
+    BINDIR="${PGDIR}/bin"
     PKGLIBDIR="${PGDIR}/lib"
     SHAREDIR="${PGDIR}/share"
     EXTENSIONDIR="${SHAREDIR}/extension"
@@ -75,6 +76,7 @@ elif [ -n "$PG_CONFIG" ]; then
     fi
     info "Using pg_config from PG_CONFIG: $PG_CONFIG"
 
+    BINDIR=$("$PG_CONFIG" --bindir)
     PKGLIBDIR=$("$PG_CONFIG" --pkglibdir)
     SHAREDIR=$("$PG_CONFIG" --sharedir)
     EXTENSIONDIR="${SHAREDIR}/extension"
@@ -85,6 +87,7 @@ elif command -v pg_config >/dev/null 2>&1; then
     PG_CONFIG="pg_config"
     info "Using pg_config from PATH: $(which pg_config)"
 
+    BINDIR=$("$PG_CONFIG" --bindir)
     PKGLIBDIR=$("$PG_CONFIG" --pkglibdir)
     SHAREDIR=$("$PG_CONFIG" --sharedir)
     EXTENSIONDIR="${SHAREDIR}/extension"
@@ -109,6 +112,7 @@ else
 fi
 
 info "PostgreSQL version: $PG_VERSION"
+info "Binary directory: $BINDIR"
 info "Library directory: $PKGLIBDIR"
 info "Extension directory: $EXTENSIONDIR"
 
@@ -130,7 +134,7 @@ fi
 
 # Determine if we need sudo
 NEED_SUDO=false
-if [ ! -w "$PKGLIBDIR" ] || [ ! -w "$EXTENSIONDIR" ]; then
+if [ ! -w "$BINDIR" ] || [ ! -w "$PKGLIBDIR" ] || [ ! -w "$EXTENSIONDIR" ]; then
     NEED_SUDO=true
     warn "Target directories require elevated permissions, using sudo"
 fi
@@ -153,6 +157,31 @@ copy_file() {
     fi
 }
 
+# Install executables (if bin directory exists in package)
+if [ -d "$SCRIPT_DIR/bin" ]; then
+    info "Installing executables..."
+
+    # Check if bin directory exists on target, create if needed
+    if [ ! -d "$BINDIR" ]; then
+        warn "Binary directory does not exist: $BINDIR"
+        echo "Creating binary directory..."
+        if [ -w "$(dirname "$BINDIR")" ]; then
+            mkdir -p "$BINDIR"
+        else
+            sudo mkdir -p "$BINDIR"
+        fi
+    fi
+
+    # Install each executable
+    for exe in "$SCRIPT_DIR"/bin/*; do
+        if [ -f "$exe" ]; then
+            filename=$(basename "$exe")
+            copy_file "$exe" "$BINDIR/$filename" 755
+            echo "  Installed: $filename"
+        fi
+    done
+fi
+
 # Install shared libraries
 info "Installing shared libraries..."
 for lib in "$SCRIPT_DIR"/lib/*.so "$SCRIPT_DIR"/lib/*.dylib; do

packaging/windows/README.md

@@ -12,6 +12,7 @@
    - If not found, you can browse to select the correct directory
 
 3. The installer copies files to:
+   - `bin\pglogical_create_subscriber.exe`
    - `lib\pglogical.dll`
    - `lib\pglogical_output.dll`
    - `share\extension\pglogical.control`
@@ -27,16 +28,32 @@
 2. Extract the ZIP to a temporary location
 
 3. Copy files to your PostgreSQL installation directory:
+   - Copy `bin\*.exe` to: `C:\Program Files\PostgreSQL\17\bin\`
    - Copy `lib\*.dll` to: `C:\Program Files\PostgreSQL\17\lib\`
    - Copy `share\extension\*` to: `C:\Program Files\PostgreSQL\17\share\extension\`
 
    **PowerShell example:**
    ```powershell
    $PG_DIR = "C:\Program Files\PostgreSQL\17"
+   Copy-Item "bin\*.exe" "$PG_DIR\bin\"
    Copy-Item "lib\*.dll" "$PG_DIR\lib\"
    Copy-Item "share\extension\*" "$PG_DIR\share\extension\"
    ```
 
+## Bundled Utilities
+
+### pglogical_create_subscriber
+
+The `pglogical_create_subscriber.exe` utility creates a new pglogical subscriber node from a physical base backup. This enables fast subscriber setup for large databases by combining physical backup with logical replication.
+
+**Usage:**
+```powershell
+# After installation, verify the utility is available
+pglogical_create_subscriber --help
+```
+
+The utility is installed to the PostgreSQL bin directory alongside other PostgreSQL tools like `psql.exe` and `pg_dump.exe`.
+
 ## Enabling the Extension
 
 After installation, enable pglogical in your database:

packaging/windows/pglogical.wxs

@@ -131,6 +131,7 @@
     <StandardDirectory Id="ProgramFiles64Folder">
       <Directory Id="PostgreSQLFolder" Name="PostgreSQL">
         <Directory Id="POSTGRESQLDIR" Name="$(var.PG_VERSION)">
+          <Directory Id="BINDIR" Name="bin" />
           <Directory Id="LIBDIR" Name="lib" />
           <Directory Id="SHAREDIR" Name="share">
             <Directory Id="EXTENSIONDIR" Name="extension" />
@@ -139,6 +140,18 @@
       </Directory>
     </StandardDirectory>
 
+    <!-- ================================================================
+         Components: Executables
+         ================================================================ -->
+
+    <ComponentGroup Id="Executables" Directory="BINDIR">
+      <Component Id="pglogical_create_subscriber_exe" Guid="*">
+        <File Id="pglogical_create_subscriber.exe"
+              Source="$(var.BuildDir)\pglogical_create_subscriber.exe"
+              KeyPath="yes" />
+      </Component>
+    </ComponentGroup>
+
     <!-- ================================================================
          Components: Shared Libraries
          ================================================================ -->
@@ -205,6 +218,7 @@
              Description="Installs the pglogical logical replication extension for PostgreSQL $(var.PG_VERSION)."
              Level="1"
              ConfigurableDirectory="POSTGRESQLDIR">
+      <ComponentGroupRef Id="Executables" />
       <ComponentGroupRef Id="Libraries" />
       <ComponentGroupRef Id="Extensions" />
       <ComponentGroupRef Id="SqlFiles" />

specs/003-distribute-create-subscriber/checklists/requirements.md

@@ -0,0 +1,44 @@
+# Specification Quality Checklist: Distribute pglogical_create_subscriber
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Validation Summary
+
+**Status**: PASSED
+
+All checklist items have been validated and passed. The specification is complete and ready for the next phase.
+
+## Notes
+
+- The feature is well-defined with clear boundaries (packaging only, no utility changes)
+- Four user stories cover all distribution formats (Windows MSI, Windows ZIP, Linux tar.gz, macOS tar.gz)
+- Success criteria are measurable and verifiable (100% package coverage, help command works)
+- Edge cases identified for permission issues and upgrades
+- Assumptions clearly documented (utility already builds, no extra dependencies)

specs/003-distribute-create-subscriber/plan.md

@@ -0,0 +1,136 @@
+# Implementation Plan: Distribute pglogical_create_subscriber
+
+**Branch**: `003-distribute-create-subscriber` | **Date**: 2026-01-08 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/003-distribute-create-subscriber/spec.md`
+
+## Summary
+
+Include the `pglogical_create_subscriber` executable in all release packages (Windows MSI, Windows ZIP, Linux tar.gz, macOS tar.gz). The utility is already built during the normal build process but is not packaged. This requires modifying the packaging scripts, WiX installer definition, CI/CD workflows, and installation script to include the executable in the appropriate `bin/` directory.
+
+## Technical Context
+
+**Language/Version**: C (PostgreSQL extension), Bash (scripts), WiX v5 (Windows MSI), YAML (GitHub Actions)
+**Primary Dependencies**: WiX Toolset v5, GitHub Actions runners, pg_config
+**Storage**: N/A (packaging feature, no data storage)
+**Testing**: Manual verification via `--help` command, existing TAP test (`t/010_pglogical_create_subscriber.pl`)
+**Target Platform**: Windows (x64), Linux (x64), macOS (ARM64)
+**Project Type**: PostgreSQL C extension with packaging automation
+**Performance Goals**: N/A (packaging feature)
+**Constraints**: Must work with existing PostgreSQL installation paths
+**Scale/Scope**: 4 package types, 4 PostgreSQL versions (15-18), 12 CI matrix jobs
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Applicable | Status | Notes |
+|-----------|-----------|--------|-------|
+| I. PostgreSQL Version Compatibility | Yes | PASS | No code changes to utility; packaging only |
+| II. Backward Compatibility | Yes | PASS | Additive change; no existing behavior modified |
+| III. Testing Discipline | Yes | PASS | Existing TAP test covers utility; acceptance via --help |
+| IV. Code Quality & Memory Safety | No | N/A | No C code changes |
+| V. Replication Integrity | No | N/A | No data path changes |
+| VI. Implementation Completeness | Yes | PASS | All 4 package types addressed, no stubs |
+
+**Gate Result**: PASS - Proceed to Phase 0
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/003-distribute-create-subscriber/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── quickstart.md        # Phase 1 output
+└── tasks.md             # Phase 2 output (/speckit.tasks command)
+```
+
+### Source Code (files to modify)
+
+```text
+packaging/
+├── unix/
+│   ├── install.sh       # Add bin/ directory handling
+│   └── README.md        # Document bundled executable
+└── windows/
+    ├── pglogical.wxs    # Add BINDIR component for exe
+    └── README.md        # Document bundled executable
+
+.github/workflows/
+└── release.yml          # Add bin/ directory and copy executable for all platforms
+```
+
+**Structure Decision**: This is a packaging-only feature. No new source files are created; existing packaging infrastructure files are modified to include the already-built executable.
+
+## Complexity Tracking
+
+No constitution violations to justify. This is a minimal-complexity packaging change.
+
+## Phase 0: Research Complete
+
+All technical unknowns resolved. See [research.md](research.md) for details on:
+- Build process (no changes needed)
+- WiX v5 packaging patterns
+- GitHub Actions modifications
+- Install script enhancement
+- Documentation updates
+
+## Phase 1: Design Complete
+
+### Artifacts Generated
+
+| Artifact | Purpose | Status |
+|----------|---------|--------|
+| research.md | Technical decisions and rationale | Complete |
+| quickstart.md | Implementation verification guide | Complete |
+
+### Data Model
+
+Not applicable - this is a packaging feature with no data entities.
+
+### API Contracts
+
+Not applicable - no API endpoints or interfaces defined.
+
+### Constitution Re-check (Post-Design)
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| I. PostgreSQL Version Compatibility | PASS | Packaging changes are version-agnostic |
+| II. Backward Compatibility | PASS | No breaking changes to existing packages |
+| III. Testing Discipline | PASS | Verification via --help + existing TAP test |
+| VI. Implementation Completeness | PASS | All 5 files fully specified |
+
+**Gate Result**: PASS - Ready for Phase 2 (/speckit.tasks)
+
+## Implementation Scope
+
+### Files to Modify
+
+1. **`.github/workflows/release.yml`**
+   - Linux packaging section: Add bin/ directory, copy executable
+   - macOS packaging section: Add bin/ directory, copy executable
+   - Windows ZIP packaging section: Add bin/ directory, copy executable
+
+2. **`packaging/windows/pglogical.wxs`**
+   - Add BINDIR StandardDirectory reference
+   - Add Executables Component with pglogical_create_subscriber.exe
+   - Add ComponentRef to Feature element
+
+3. **`packaging/unix/install.sh`**
+   - Add BINDIR detection via `pg_config --bindir`
+   - Add loop to install executables from bin/ subdirectory
+   - Handle permissions (sudo) for bin directory
+
+4. **`packaging/unix/README.md`**
+   - Add section describing bundled executable
+   - Add verification command example
+
+5. **`packaging/windows/README.md`**
+   - Add section describing bundled executable
+   - Add verification command example
+
+### Files Created (None)
+
+No new files are created for this feature.