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
 # -----------------------------------------------------------------------------