Implement new SDK APIs

.gitignore

@@ -7,6 +7,7 @@ dist/
 # Native library directories
 native/
 test-project-api/
+examples/api/test-project-*/
 
 # Python cache
 __pycache__/

dump-version.sh

@@ -14,9 +14,13 @@
 #   1. Fetch latest version from gopher-orch releases
 #   2. Validate and determine the target version
 #   3. Update pyproject.toml (main and platform packages)
-#   4. Update __init__.py files
-#   5. Update CHANGELOG.md ([Unreleased] -> [X.Y.Z] - date)
-#   6. Commit the changes
+#   4. Auto-populate CHANGELOG.md [Unreleased] section from:
+#        - git log of this repo since the previous tag
+#        - the gopher-orch GitHub release notes for the new version
+#      (manual entries already in [Unreleased] are preserved and shown first)
+#   5. Update __init__.py files and platform packages
+#   6. Promote [Unreleased] -> [X.Y.Z] - date
+#   7. Commit the changes
 #
 # After running this script:
 #   1. Review the changes: git diff HEAD~1
@@ -148,34 +152,181 @@ if [ "$CURRENT_VERSION" = "$TARGET_VERSION" ]; then
 fi
 
 # -----------------------------------------------------------------------------
-# Step 4: Check [Unreleased] section has content
+# Step 4: Build release notes from git log + gopher-orch release notes
 # -----------------------------------------------------------------------------
 echo ""
-echo -e "${YELLOW}Step 4: Checking [Unreleased] section...${NC}"
+echo -e "${YELLOW}Step 4: Building release notes...${NC}"
 
 if [ ! -f "$CHANGELOG_FILE" ]; then
     echo -e "${RED}Error: $CHANGELOG_FILE not found${NC}"
     exit 1
 fi
 
-# Extract content between [Unreleased] and next ## section
-UNRELEASED_CONTENT=$(sed -n '/^## \[Unreleased\]/,/^## \[/p' "$CHANGELOG_FILE" | \
-    grep -v "^## \[" | grep -v "^$" | head -20)
+# Fetch tags so PREV_TAG resolution is accurate even on shallow clones
+git fetch --tags --quiet 2>/dev/null || true
 
-if [ -z "$UNRELEASED_CONTENT" ]; then
-    echo -e "${YELLOW}Warning: [Unreleased] section in CHANGELOG.md appears empty${NC}"
-    echo "You may want to add release notes before continuing."
-    read -p "Continue anyway? (y/N) " -n 1 -r
-    echo
-    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-        exit 1
+# Previous Python tag reachable from HEAD. Prefer the highest version tag
+# directly on HEAD when release tags are stacked on one commit; otherwise use
+# git describe to keep the range anchored to this branch.
+PREV_TAG=$(git tag --points-at HEAD --list 'v*' --sort=-v:refname | head -1)
+if [ -z "$PREV_TAG" ]; then
+    PREV_TAG=$(git describe --tags --abbrev=0 --match 'v*' HEAD 2>/dev/null || true)
+fi
+if [ -n "$PREV_TAG" ]; then
+    echo -e "  Previous Python tag:    ${CYAN}$PREV_TAG${NC}"
+    PY_RANGE="$PREV_TAG..HEAD"
+else
+    echo -e "  Previous Python tag:    ${YELLOW}none (first release)${NC}"
+    PY_RANGE="HEAD"
+fi
+
+# Previous gopher-orch version from the package version recorded at the
+# previous tag. Extended Python versions are X.Y.Z.E, where X.Y.Z tracks
+# gopher-orch.
+PREV_GOPHER_ORCH_VERSION=""
+if [ -n "$PREV_TAG" ]; then
+    PREV_PY_VERSION=$(git show "$PREV_TAG:$PYPROJECT_TOML" 2>/dev/null | \
+        grep -E '^version\s*=' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
+    if echo "$PREV_PY_VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$'; then
+        PREV_GOPHER_ORCH_VERSION=$(echo "$PREV_PY_VERSION" | \
+            sed -E 's/^([0-9]+\.[0-9]+\.[0-9]+)(\.[0-9]+)?$/\1/')
+        PREV_TAG_BASE=$(echo "${PREV_TAG#v}" | sed -E 's/^([0-9]+\.[0-9]+\.[0-9]+).*/\1/')
+        if [ "$PREV_GOPHER_ORCH_VERSION" != "$PREV_TAG_BASE" ]; then
+            echo -e "  ${YELLOW}Warning: $PREV_TAG records package version $PREV_PY_VERSION; tag name and recorded version disagree${NC}"
+            PREV_GOPHER_ORCH_VERSION=""
+        fi
+    elif [ -n "$PREV_PY_VERSION" ]; then
+        echo -e "  ${YELLOW}Warning: could not derive previous gopher-orch version from $PREV_TAG:$PYPROJECT_TOML version '$PREV_PY_VERSION'${NC}"
+    else
+        echo -e "  ${YELLOW}Warning: could not read previous package version from $PREV_TAG:$PYPROJECT_TOML${NC}"
     fi
+fi
+if [ -n "$PREV_GOPHER_ORCH_VERSION" ]; then
+    echo -e "  Previous gopher-orch:   ${CYAN}v$PREV_GOPHER_ORCH_VERSION${NC}"
+else
+    echo -e "  Previous gopher-orch:   ${YELLOW}unknown${NC}"
+fi
+echo -e "  New gopher-orch:        ${GREEN}v$GOPHER_ORCH_VERSION${NC}"
+
+if ! grep -q '^## \[Unreleased\]' "$CHANGELOG_FILE"; then
+    echo -e "${RED}Error: [Unreleased] section not found in $CHANGELOG_FILE${NC}"
+    exit 1
+fi
+
+# Preserve any manually-authored entries already under [Unreleased]
+MANUAL_CONTENT=$(awk '
+    /^## \[Unreleased\]/ { capture = 1; next }
+    /^## \[/ && capture { capture = 0 }
+    capture { print }
+' "$CHANGELOG_FILE")
+
+# Collect Python repo commits since previous tag (skip merges + prior release commits)
+PY_COMMITS=$(git log --no-merges --pretty=format:'- %s' \
+    --invert-grep --grep='^Release version' --grep='^\[release\]' \
+    $PY_RANGE 2>/dev/null || true)
+
+PY_COMMIT_COUNT=0
+if [ -n "$PY_COMMITS" ]; then
+    PY_COMMIT_COUNT=$(printf '%s\n' "$PY_COMMITS" | wc -l | tr -d ' ')
+fi
+echo -e "  Python commits in range:${GREEN} $PY_COMMIT_COUNT${NC}"
+if [ -n "$PREV_TAG" ] && [ "$PY_COMMIT_COUNT" -eq 0 ]; then
+    echo -e "  ${YELLOW}Warning: no Python SDK commits found in $PY_RANGE; SDK changes section will be omitted.${NC}"
+fi
+
+# Extract the "What's Changed" block from the gopher-orch release notes,
+# stripping the Build Information preamble and the trailing Full Changelog link.
+# Rewrite PR refs and user mentions so this repo's rendered changelog does not
+# point #NNN at gopher-mcp-python or ping users from the upstream release.
+GOPHER_ORCH_NOTES=$(gh release view "v$GOPHER_ORCH_VERSION" \
+    --repo GopherSecurity/gopher-orch \
+    --json body -q '.body' 2>/dev/null | \
+    awk '
+        /^## What.s Changed/ { capture = 1; next }
+        /^\*\*Full Changelog\*\*/ { capture = 0 }
+        capture { print }
+    ' | sed -E \
+        -e '/^---$/d' \
+        -e 's/#([0-9]+)/https:\/\/github.com\/GopherSecurity\/gopher-orch\/pull\/\1/g' \
+        -e 's/@([A-Za-z0-9][A-Za-z0-9-]*)/github.com\/\1/g')
+
+if [ -n "$GOPHER_ORCH_NOTES" ]; then
+    echo -e "  gopher-orch notes:      ${GREEN}fetched${NC}"
 else
-    echo -e "  ${GREEN}[Unreleased] section has content${NC}"
-    echo "  Preview:"
-    echo "$UNRELEASED_CONTENT" | head -5 | sed 's/^/    /'
+    echo -e "  gopher-orch notes:      ${YELLOW}empty (using link only)${NC}"
 fi
 
+# Build the new [Unreleased] body
+RELEASE_NOTES_FILE=$(mktemp)
+CHANGELOG_TMP="${CHANGELOG_FILE}.gen"
+trap 'rm -f "$RELEASE_NOTES_FILE" "$CHANGELOG_TMP"' EXIT
+{
+    if printf '%s' "$MANUAL_CONTENT" | grep -q '[^[:space:]]'; then
+        printf '%s\n\n' "$MANUAL_CONTENT"
+    fi
+
+    echo "### Changed"
+    echo ""
+    if [ -n "$PREV_GOPHER_ORCH_VERSION" ] && \
+       [ "$PREV_GOPHER_ORCH_VERSION" != "$GOPHER_ORCH_VERSION" ]; then
+        echo "- Bump \`gopher-orch\` native library from v$PREV_GOPHER_ORCH_VERSION to [v$GOPHER_ORCH_VERSION](https://github.com/GopherSecurity/gopher-orch/releases/tag/v$GOPHER_ORCH_VERSION)."
+    else
+        echo "- Pin \`gopher-orch\` native library to [v$GOPHER_ORCH_VERSION](https://github.com/GopherSecurity/gopher-orch/releases/tag/v$GOPHER_ORCH_VERSION)."
+    fi
+    echo ""
+
+    if [ -n "$PY_COMMITS" ]; then
+        if [ -n "$PREV_TAG" ]; then
+            echo "#### SDK changes since $PREV_TAG"
+        else
+            echo "#### SDK changes"
+        fi
+        echo ""
+        printf '%s\n' "$PY_COMMITS"
+        echo ""
+    fi
+
+    if [ -n "$GOPHER_ORCH_NOTES" ]; then
+        echo "#### gopher-orch v$GOPHER_ORCH_VERSION highlights"
+        echo ""
+        printf '%s\n' "$GOPHER_ORCH_NOTES"
+    fi
+} > "$RELEASE_NOTES_FILE"
+
+# Splice the generated body in: replace everything between
+# "## [Unreleased]" and the next "## [" with the new content.
+awk -v notes_file="$RELEASE_NOTES_FILE" '
+    BEGIN {
+        while ((getline line < notes_file) > 0) {
+            notes = notes (notes ? "\n" : "") line
+        }
+        close(notes_file)
+    }
+    /^## \[Unreleased\]/ {
+        print
+        print ""
+        print notes
+        print ""
+        skipping = 1
+        next
+    }
+    /^## \[/ && skipping { skipping = 0 }
+    skipping { next }
+    { print }
+' "$CHANGELOG_FILE" > "$CHANGELOG_TMP"
+mv "$CHANGELOG_TMP" "$CHANGELOG_FILE"
+
+# Recompute UNRELEASED_CONTENT for the eventual commit message
+UNRELEASED_CONTENT=$(awk '
+    /^## \[Unreleased\]/ { capture = 1; next }
+    /^## \[/ && capture { capture = 0 }
+    capture { print }
+' "$CHANGELOG_FILE" | sed -e '/^[[:space:]]*$/d')
+
+echo -e "  ${GREEN}[Unreleased] section populated${NC}"
+echo "  Preview:"
+printf '%s\n' "$UNRELEASED_CONTENT" | head -12 | sed 's/^/    /'
+
 # -----------------------------------------------------------------------------
 # Step 5: Update version files
 # -----------------------------------------------------------------------------