python-package-folder 4.0.0__tar.gz → 4.1.1__tar.gz

{python_package_folder-4.0.0 → python_package_folder-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-package-folder
-Version: 4.0.0
+Version: 4.1.1
 Summary: Python package to automatically package and build a folder, fetching all relevant dependencies.
 Project-URL: Repository, https://github.com/alelom/python-package-folder
 Author-email: Alessio Lombardi <work@alelom.com>
@@ -475,15 +475,32 @@ The `--version` option:
 
 When `--version` is not provided, the tool can automatically determine the next version using semantic-release. This requires Node.js, npm, and semantic-release to be installed.
 
+**Version Detection:**
+- **Baseline version**:
+  - **Registry Query (Preferred)**: When publishing to a repository (PyPI, TestPyPI, or Azure Artifacts), the tool queries the target registry for the latest published version and uses it as the baseline for version calculation. This ensures version calculations are based on what's actually published, not just git tags.
+  - **Git Tags (Fallback)**: If the package doesn't exist on the registry yet (first release) or if registry query fails, the tool falls back to using git tags to determine the starting version.
+- **New version to publish**: After determining the baseline version, [`semantic-release`](https://semantic-release.gitbook.io/semantic-release/) analyzes commits since that version to calculate the next version bump (major, minor, or patch) based on [_conventional commit_](https://www.conventionalcommits.org/en/v1.0.0/) messages.
+
 **For subfolder builds (Workflow 1):**
 - Uses per-package tags: `{package-name}-v{version}` (e.g., `my-package-v1.2.3`)
+- Queries the target registry for the latest published version of the subfolder package
 - Filters commits to only those affecting the subfolder path
+- **Commit filtering behavior**: Only commits that modify files within the subfolder path are considered for version calculation. Commits that only target files outside the subfolder are excluded. For example:
+  - `fix: update my_subfolder/foo.py` → **Included** (affects subfolder)
+  - `feat: add feature to other_package/bar.py` → **Excluded** (doesn't affect subfolder)
+  - `fix: update my_subfolder/baz.py and shared/utils.py` → **Included** (affects subfolder, even if it also touches files outside)
 - Requires `semantic-release-commit-filter` plugin
 
 **For main package builds (Workflow 2):**
 - Uses repo-level tags: `v{version}` (e.g., `v1.2.3`)
+- Queries the target registry for the latest published version when publishing
 - Analyzes all commits in the repository
 
+**Registry Support:**
+- **PyPI**: Fully supported via JSON API (`https://pypi.org/pypi/{package-name}/json`)
+- **TestPyPI**: Fully supported via JSON API (`https://test.pypi.org/pypi/{package-name}/json`)
+- **Azure Artifacts**: Basic support with fallback to git tags. Azure Artifacts uses a different API format and may require authentication, so if the query fails, the tool automatically falls back to git tags.
+
 **Setup:**
 ```bash
 # Install semantic-release globally

{python_package_folder-4.0.0 → python_package_folder-4.1.1}/README.md

@@ -455,15 +455,32 @@ The `--version` option:
 
 When `--version` is not provided, the tool can automatically determine the next version using semantic-release. This requires Node.js, npm, and semantic-release to be installed.
 
+**Version Detection:**
+- **Baseline version**:
+  - **Registry Query (Preferred)**: When publishing to a repository (PyPI, TestPyPI, or Azure Artifacts), the tool queries the target registry for the latest published version and uses it as the baseline for version calculation. This ensures version calculations are based on what's actually published, not just git tags.
+  - **Git Tags (Fallback)**: If the package doesn't exist on the registry yet (first release) or if registry query fails, the tool falls back to using git tags to determine the starting version.
+- **New version to publish**: After determining the baseline version, [`semantic-release`](https://semantic-release.gitbook.io/semantic-release/) analyzes commits since that version to calculate the next version bump (major, minor, or patch) based on [_conventional commit_](https://www.conventionalcommits.org/en/v1.0.0/) messages.
+
 **For subfolder builds (Workflow 1):**
 - Uses per-package tags: `{package-name}-v{version}` (e.g., `my-package-v1.2.3`)
+- Queries the target registry for the latest published version of the subfolder package
 - Filters commits to only those affecting the subfolder path
+- **Commit filtering behavior**: Only commits that modify files within the subfolder path are considered for version calculation. Commits that only target files outside the subfolder are excluded. For example:
+  - `fix: update my_subfolder/foo.py` → **Included** (affects subfolder)
+  - `feat: add feature to other_package/bar.py` → **Excluded** (doesn't affect subfolder)
+  - `fix: update my_subfolder/baz.py and shared/utils.py` → **Included** (affects subfolder, even if it also touches files outside)
 - Requires `semantic-release-commit-filter` plugin
 
 **For main package builds (Workflow 2):**
 - Uses repo-level tags: `v{version}` (e.g., `v1.2.3`)
+- Queries the target registry for the latest published version when publishing
 - Analyzes all commits in the repository
 
+**Registry Support:**
+- **PyPI**: Fully supported via JSON API (`https://pypi.org/pypi/{package-name}/json`)
+- **TestPyPI**: Fully supported via JSON API (`https://test.pypi.org/pypi/{package-name}/json`)
+- **Azure Artifacts**: Basic support with fallback to git tags. Azure Artifacts uses a different API format and may require authentication, so if the query fails, the tool automatically falls back to git tags.
+
 **Setup:**
 ```bash
 # Install semantic-release globally

{python_package_folder-4.0.0 → python_package_folder-4.1.1}/coverage.svg

@@ -14,7 +14,7 @@
   <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
     <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
     <text x="31.5" y="14">coverage</text>
-    <text x="81" y="15" fill="#010101" fill-opacity=".3">66%</text>
-    <text x="81" y="14">66%</text>
+    <text x="81" y="15" fill="#010101" fill-opacity=".3">64%</text>
+    <text x="81" y="14">64%</text>
   </g>
 </svg>

{python_package_folder-4.0.0 → python_package_folder-4.1.1}/pyproject.toml

@@ -42,7 +42,7 @@ dependencies = [
 
 # ---- Dev dependencies ----
 
-version = "4.0.0"
+version = "4.1.1"
 [dependency-groups]
 dev = [
     "pytest>=8.3.5",

{python_package_folder-4.0.0 → python_package_folder-4.1.1/python_package_folder}/scripts/get-next-version.cjs

@@ -7,12 +7,14 @@
  * package builds (repo-level tags).
  * 
  * Usage:
- *   node scripts/get-next-version.cjs <project_root> [subfolder_path] [package_name]
+ *   node scripts/get-next-version.cjs <project_root> [subfolder_path] [package_name] [repository] [repository_url]
  * 
  * Args:
  *   - project_root: Root directory of the project (absolute or relative path)
  *   - subfolder_path: Optional. Path to subfolder relative to project_root (for Workflow 1)
  *   - package_name: Optional. Package name for subfolder builds (for per-package tags)
+ *   - repository: Optional. Target repository ('pypi', 'testpypi', or 'azure')
+ *   - repository_url: Optional. Repository URL (required for Azure Artifacts)
  * 
  * Output:
  *   - Version string (e.g., "1.2.3") if a release is determined
@@ -22,25 +24,32 @@
 
 const path = require('path');
 const fs = require('fs');
+const https = require('https');
+const http = require('http');
 
 // Parse command line arguments
 const args = process.argv.slice(2);
 if (args.length < 1) {
   console.error('Error: project_root is required');
-  console.error('Usage: node get-next-version.cjs <project_root> [subfolder_path] [package_name]');
+  console.error('Usage: node get-next-version.cjs <project_root> [subfolder_path] [package_name] [repository] [repository_url]');
   process.exit(1);
 }
 
 const projectRoot = path.resolve(args[0]);
-const subfolderPath = args[1] || null;
-const packageName = args[2] || null;
+const subfolderPath = args[1] && args[1] !== 'null' && args[1] !== '' ? args[1] : null;
+const packageName = args[2] && args[2] !== 'null' && args[2] !== '' ? args[2] : null;
+const repository = args[3] && args[3] !== 'null' && args[3] !== '' ? args[3] : null;
+const repositoryUrl = args[4] && args[4] !== 'null' && args[4] !== '' ? args[4] : null;
 
-// Validate argument combination: both-or-neither for subfolder builds
-if ((subfolderPath !== null && packageName === null) || (subfolderPath === null && packageName !== null)) {
-  console.error('Error: subfolder_path and package_name must be provided together (both or neither).');
-  console.error('Usage: node get-next-version.cjs <project_root> [subfolder_path] [package_name]');
+// Validate argument combination
+// - For subfolder builds: both subfolder_path and package_name are required
+// - For main package builds: package_name can be provided alone (for registry queries)
+if (subfolderPath !== null && packageName === null) {
+  console.error('Error: package_name is required when subfolder_path is provided.');
+  console.error('Usage: node get-next-version.cjs <project_root> [subfolder_path] [package_name] [repository] [repository_url]');
   process.exit(1);
 }
+// Note: package_name can be provided without subfolder_path for main package registry queries
 
 // Check if project root exists
 if (!fs.existsSync(projectRoot)) {
@@ -49,6 +58,8 @@ if (!fs.existsSync(projectRoot)) {
 }
 
 // Determine if this is a subfolder build
+// A subfolder build requires both subfolder_path and package_name
+// package_name alone (without subfolder_path) indicates a main package build with registry query
 const isSubfolderBuild = subfolderPath !== null && packageName !== null;
 const workingDir = isSubfolderBuild 
   ? path.resolve(projectRoot, subfolderPath)
@@ -173,10 +184,138 @@ if (isSubfolderBuild) {
   }
 }
 
-try {
-  // Try to require semantic-release
-  // First try resolving from project root (for devDependencies), then fall back to global
-  let semanticRelease;
+/**
+ * Query PyPI or TestPyPI JSON API for the latest version of a package.
+ * @param {string} packageName - Package name to query
+ * @param {string} registry - 'pypi' or 'testpypi'
+ * @returns {Promise<string|null>} Latest version string or null if not found
+ */
+async function queryPyPIVersion(packageName, registry) {
+  const baseUrl = registry === 'testpypi' 
+    ? 'https://test.pypi.org'
+    : 'https://pypi.org';
+  const url = `${baseUrl}/pypi/${packageName}/json`;
+  
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      let data = '';
+      
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      
+      res.on('end', () => {
+        if (res.statusCode === 404) {
+          // Package doesn't exist yet (first release)
+          resolve(null);
+        } else if (res.statusCode === 200) {
+          try {
+            const json = JSON.parse(data);
+            // Get latest version from info.version or releases
+            const version = json.info?.version || Object.keys(json.releases || {}).pop() || null;
+            resolve(version);
+          } catch (e) {
+            reject(new Error(`Failed to parse PyPI response: ${e.message}`));
+          }
+        } else {
+          reject(new Error(`PyPI API returned status ${res.statusCode}`));
+        }
+      });
+    }).on('error', (err) => {
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Query Azure Artifacts for the latest version of a package.
+ * Azure Artifacts uses a simple index format (HTML) which is more complex to parse.
+ * For now, we'll attempt to query but fall back gracefully if it fails.
+ * @param {string} packageName - Package name to query
+ * @param {string} repositoryUrl - Azure Artifacts repository URL
+ * @returns {Promise<string|null>} Latest version string or null if not found/unsupported
+ */
+async function queryAzureArtifactsVersion(packageName, repositoryUrl) {
+  // Convert upload URL to simple index URL
+  // Upload: https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/FEED/pypi/upload
+  // Simple: https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/FEED/pypi/simple/{package}/
+  let simpleIndexUrl;
+  try {
+    const url = new URL(repositoryUrl);
+    if (url.pathname.endsWith('/upload')) {
+      simpleIndexUrl = repositoryUrl.replace('/upload', `/simple/${packageName}/`);
+    } else {
+      // Try to construct from common patterns
+      simpleIndexUrl = repositoryUrl.replace(/\/upload$/, `/simple/${packageName}/`);
+    }
+  } catch (e) {
+    // Invalid URL format, return null to fall back to git tags
+    return null;
+  }
+  
+  return new Promise((resolve) => {
+    // Azure Artifacts may require authentication and returns HTML
+    // For now, we'll attempt the request but gracefully fall back if it fails
+    // This is a limitation - Azure Artifacts API is more complex than PyPI
+    const url = new URL(simpleIndexUrl);
+    const client = url.protocol === 'https:' ? https : http;
+    
+    const req = client.get(simpleIndexUrl, (res) => {
+      // Azure Artifacts simple index returns HTML, not JSON
+      // Parsing HTML is complex and may require authentication
+      // For now, we'll return null to fall back to git tags
+      // This can be enhanced later with proper HTML parsing or API endpoint discovery
+      resolve(null);
+    });
+    
+    req.on('error', () => {
+      // Network error or authentication required - fall back to git tags
+      resolve(null);
+    });
+    
+    req.setTimeout(5000, () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+/**
+ * Query the package registry for the latest published version.
+ * @param {string} packageName - Package name to query
+ * @param {string|null} repository - Repository type ('pypi', 'testpypi', 'azure', or null)
+ * @param {string|null} repositoryUrl - Repository URL (for Azure)
+ * @returns {Promise<string|null>} Latest version or null if not found/unsupported
+ */
+async function queryRegistryVersion(packageName, repository, repositoryUrl) {
+  if (!repository || !packageName) {
+    return null;
+  }
+  
+  try {
+    if (repository === 'pypi' || repository === 'testpypi') {
+      return await queryPyPIVersion(packageName, repository);
+    } else if (repository === 'azure') {
+      if (!repositoryUrl) {
+        return null;
+      }
+      return await queryAzureArtifactsVersion(packageName, repositoryUrl);
+    }
+  } catch (error) {
+    // Log error but don't fail - fall back to git tags
+    console.error(`Warning: Failed to query ${repository} for latest version: ${error.message}`);
+    console.error('Falling back to git tags for version detection.');
+  }
+  
+  return null;
+}
+
+// Main execution
+(async () => {
+  try {
+    // Try to require semantic-release
+    // First try resolving from project root (for devDependencies), then fall back to global
+    let semanticRelease;
   try {
     const semanticReleasePath = require.resolve('semantic-release', { paths: [projectRoot] });
     semanticRelease = require(semanticReleasePath);
@@ -214,11 +353,41 @@ try {
     }
   }
 
+  // Query registry for latest version if repository info is provided
+  let registryVersion = null;
+  if (repository && packageName) {
+    try {
+      registryVersion = await queryRegistryVersion(packageName, repository, repositoryUrl);
+      if (registryVersion) {
+        console.error(`Found latest version on ${repository}: ${registryVersion}`);
+      } else {
+        console.error(`Package not found on ${repository} or query failed, using git tags as fallback`);
+      }
+    } catch (error) {
+      console.error(`Warning: Registry query failed: ${error.message}`);
+      console.error('Falling back to git tags for version detection.');
+    }
+  }
+
   // Configure semantic-release options
   const options = {
     dryRun: true,
     ci: false,
   };
+  
+  // If we have a registry version, we can use it to set lastRelease in semantic-release context
+  // This ensures semantic-release uses the registry version as baseline instead of git tags
+  if (registryVersion) {
+    // Set lastRelease in options to use registry version as baseline
+    // This tells semantic-release to analyze commits since this version
+    options.lastRelease = {
+      version: registryVersion,
+      gitTag: isSubfolderBuild 
+        ? `${packageName}-v${registryVersion}`
+        : `v${registryVersion}`,
+      gitHead: null, // We don't know the commit, but semantic-release will find it
+    };
+  }
 
   // For subfolder builds, configure commit filter and per-package tags
   if (isSubfolderBuild) {
@@ -334,50 +503,51 @@ try {
     }
     process.exit(1);
   });
-} catch (error) {
-  // Clean up temporary package.json on error
-  if (tempPackageJson && fs.existsSync(tempPackageJson)) {
-    const backup = tempPackageJson + '.backup';
-    if (backupCreatedByScript && fs.existsSync(backup)) {
-      try {
-        // Restore original (only if we created the backup)
-        fs.copyFileSync(backup, tempPackageJson);
-        fs.unlinkSync(backup);
-      } catch (e) {
-        // Ignore cleanup errors
-      }
-    } else if (fileCreatedByScript) {
-      try {
-        // Remove temporary file (only if we created it, not if it existed before)
-        fs.unlinkSync(tempPackageJson);
-      } catch (e) {
-        // Ignore cleanup errors
-      }
-    } else if (originalPackageJsonContent !== null) {
-      // We modified an existing file but didn't create a backup (user's backup exists)
-      // Restore from the original content we stored, but don't delete user's backup
-      try {
-        fs.writeFileSync(tempPackageJson, originalPackageJsonContent, 'utf8');
-      } catch (e) {
-        // Ignore cleanup errors
+  } catch (error) {
+    // Clean up temporary package.json on error
+    if (tempPackageJson && fs.existsSync(tempPackageJson)) {
+      const backup = tempPackageJson + '.backup';
+      if (backupCreatedByScript && fs.existsSync(backup)) {
+        try {
+          // Restore original (only if we created the backup)
+          fs.copyFileSync(backup, tempPackageJson);
+          fs.unlinkSync(backup);
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      } else if (fileCreatedByScript) {
+        try {
+          // Remove temporary file (only if we created it, not if it existed before)
+          fs.unlinkSync(tempPackageJson);
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      } else if (originalPackageJsonContent !== null) {
+        // We modified an existing file but didn't create a backup (user's backup exists)
+        // Restore from the original content we stored, but don't delete user's backup
+        try {
+          fs.writeFileSync(tempPackageJson, originalPackageJsonContent, 'utf8');
+        } catch (e) {
+          // Ignore cleanup errors
+        }
       }
     }
-  }
 
-  // Check if it's a "no release" case (common, not an error)
-  if (error.message && (
-    error.message.includes('no release') ||
-    error.message.includes('No release') ||
-    error.code === 'ENOCHANGE'
-  )) {
-    console.log('none');
-    process.exit(0);
-  }
+    // Check if it's a "no release" case (common, not an error)
+    if (error.message && (
+      error.message.includes('no release') ||
+      error.message.includes('No release') ||
+      error.code === 'ENOCHANGE'
+    )) {
+      console.log('none');
+      process.exit(0);
+    }
 
-  // Other errors
-  console.error(`Error: ${error.message}`);
-  if (error.stack) {
-    console.error(error.stack);
+    // Other errors
+    console.error(`Error: ${error.message}`);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
   }
-  process.exit(1);
-}
+})();

{python_package_folder-4.0.0 → python_package_folder-4.1.1}/src/python_package_folder/python_package_folder.py

@@ -10,6 +10,8 @@ It can be invoked via:
 
 from __future__ import annotations
 
+import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -23,11 +25,23 @@ from .manager import BuildManager
 from .utils import find_project_root, find_source_directory
 
 
+def is_github_actions() -> bool:
+    """Check if running in GitHub Actions."""
+    return os.getenv("GITHUB_ACTIONS") == "true"
+
+
+def check_node_available() -> bool:
+    """Check if Node.js is available."""
+    return shutil.which("node") is not None
+
+
 def resolve_version_via_semantic_release(
     project_root: Path,
     subfolder_path: Path | None = None,
     package_name: str | None = None,
-) -> str | None:
+    repository: str | None = None,
+    repository_url: str | None = None,
+) -> tuple[str | None, str | None]:
     """
     Resolve the next version using semantic-release via Node.js script.
 
@@ -35,10 +49,38 @@ def resolve_version_via_semantic_release(
         project_root: Root directory of the project
         subfolder_path: Optional path to subfolder (relative to project_root) for Workflow 1
         package_name: Optional package name for subfolder builds
+        repository: Optional target repository ('pypi', 'testpypi', or 'azure')
+        repository_url: Optional repository URL (required for Azure Artifacts)
 
     Returns:
-        Version string if a release is determined, None if no release or error
+        Tuple of (version string if a release is determined, error message if any)
+        Returns (None, None) if no release or no error, (None, error_msg) on error
     """
+    # Note: Node.js availability should be checked before calling this function
+    # This check is a safety fallback
+    if not check_node_available():
+        if is_github_actions():
+            error_msg = """Node.js is not available in this GitHub Actions workflow.
+
+To fix this, add the following steps BEFORE running python-package-folder:
+
+- name: Setup Node.js
+  uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+
+- name: Install semantic-release
+  run: |
+    npm install -g semantic-release semantic-release-commit-filter
+
+Alternatively, provide --version explicitly to skip automatic version resolution."""
+            print(f"Error: {error_msg}", file=sys.stderr)
+            return None, error_msg
+        else:
+            error_msg = "Node.js not found. Cannot resolve version via semantic-release."
+            print(f"Error: {error_msg}", file=sys.stderr)
+            return None, error_msg
+
     # Try to find the script in multiple locations:
     # 1. Project root / scripts (for development or when script is in repo)
     # 2. Package installation directory / scripts (for installed package)
@@ -86,7 +128,9 @@ def resolve_version_via_semantic_release(
                     script_path = fallback_script
 
         if not script_path:
-            return None
+            error_msg = "Could not locate get-next-version.cjs script"
+            print(f"Error: {error_msg}", file=sys.stderr)
+            return None, error_msg
 
         # Build command arguments
         cmd = ["node", str(script_path), str(project_root)]
@@ -98,7 +142,17 @@ def resolve_version_via_semantic_release(
                 else subfolder_path
             )
             cmd.extend([str(rel_path), package_name])
-        # Workflow 2: main package (no additional args needed)
+        elif package_name:
+            # Main package build with package_name (for registry queries)
+            # Pass null for subfolder_path, then package_name
+            cmd.extend(["", package_name])
+        # Workflow 2: main package without package_name (no additional args needed)
+        
+        # Add repository information if provided
+        if repository:
+            cmd.append(repository)
+            if repository_url:
+                cmd.append(repository_url)
 
         result = subprocess.run(
             cmd,
@@ -109,38 +163,53 @@ def resolve_version_via_semantic_release(
         )
 
         if result.returncode != 0:
-            # Log error details for debugging
+            # Collect error details
+            error_details = []
             if result.stderr:
-                print(
-                    f"Warning: semantic-release version resolution failed: {result.stderr}",
-                    file=sys.stderr,
-                )
-            elif result.stdout:
-                print(
-                    f"Warning: semantic-release version resolution failed: {result.stdout}",
-                    file=sys.stderr,
-                )
-            return None
+                error_details.append(f"stderr: {result.stderr}")
+            if result.stdout:
+                error_details.append(f"stdout: {result.stdout}")
+            
+            error_msg = "semantic-release version resolution failed"
+            if error_details:
+                error_msg += f": {'; '.join(error_details)}"
+            
+            print(f"Error: {error_msg}", file=sys.stderr)
+            return None, error_msg
 
         version = result.stdout.strip()
         if version and version != "none":
-            return version
+            return version, None
 
-        return None
+        return None, None
     except FileNotFoundError:
-        # Node.js not found
-        print(
-            "Warning: Node.js not found. Cannot resolve version via semantic-release.",
-            file=sys.stderr,
-        )
-        return None
+        # Node.js not found (shouldn't happen if check_node_available() passed, but handle gracefully)
+        if is_github_actions():
+            error_msg = """Node.js is not available in this GitHub Actions workflow.
+
+To fix this, add the following steps BEFORE running python-package-folder:
+
+- name: Setup Node.js
+  uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+
+- name: Install semantic-release
+  run: |
+    npm install -g semantic-release semantic-release-commit-filter
+
+Alternatively, provide --version explicitly to skip automatic version resolution."""
+            print(f"Error: {error_msg}", file=sys.stderr)
+            return None, error_msg
+        else:
+            error_msg = "Node.js not found. Cannot resolve version via semantic-release."
+            print(f"Error: {error_msg}", file=sys.stderr)
+            return None, error_msg
     except Exception as e:
         # Other errors (e.g., permission issues, script not found)
-        print(
-            f"Warning: Error resolving version via semantic-release: {e}",
-            file=sys.stderr,
-        )
-        return None
+        error_msg = f"Error resolving version via semantic-release: {e}"
+        print(f"Error: {error_msg}", file=sys.stderr)
+        return None, error_msg
     finally:
         # Clean up temporary file if we extracted from zip/pex
         # This must be at function level to ensure cleanup even on early return
@@ -297,6 +366,50 @@ def main() -> int:
             # Version is needed for subfolder builds or when publishing main package
             if is_subfolder or args.publish:
                 print("No --version provided, attempting to resolve via semantic-release...")
+                
+                # Check Node.js availability upfront
+                if not check_node_available():
+                    if is_github_actions():
+                        error_msg = """Node.js is not available in this GitHub Actions workflow.
+
+To fix this, add the following steps BEFORE running python-package-folder:
+
+- name: Setup Node.js
+  uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+
+- name: Install semantic-release
+  run: |
+    npm install -g semantic-release semantic-release-commit-filter
+
+Alternatively, provide --version explicitly to skip automatic version resolution."""
+                        print(f"Error: {error_msg}", file=sys.stderr)
+                    else:
+                        print(
+                            "Error: Node.js is not available. Cannot resolve version via semantic-release.",
+                            file=sys.stderr,
+                        )
+                        print(
+                            "Please install Node.js or provide --version explicitly.",
+                            file=sys.stderr,
+                        )
+                    return 1
+                
+                # Log that Node.js is available (for debugging)
+                node_version = subprocess.run(
+                    ["node", "--version"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if node_version.returncode == 0:
+                    print(f"Node.js detected: {node_version.stdout.strip()}")
+                
+                # Get repository info if publishing
+                repository = args.publish if args.publish else None
+                repository_url = args.repository_url if args.publish else None
+                
                 if is_subfolder:
                     # Workflow 1: subfolder build
                     # src_dir is guaranteed to be relative to project_root due to is_subfolder check
@@ -304,12 +417,35 @@ def main() -> int:
                         " ", "-"
                     ).lower().strip("-")
                     subfolder_rel_path = src_dir.relative_to(project_root)
-                    resolved_version = resolve_version_via_semantic_release(
-                        project_root, subfolder_rel_path, package_name
+                    resolved_version, error_details = resolve_version_via_semantic_release(
+                        project_root,
+                        subfolder_rel_path,
+                        package_name,
+                        repository=repository,
+                        repository_url=repository_url,
                     )
                 else:
                     # Workflow 2: main package
-                    resolved_version = resolve_version_via_semantic_release(project_root)
+                    # For main package, we need package_name from pyproject.toml for registry queries
+                    package_name_for_registry = None
+                    if repository:
+                        try:
+                            import tomllib
+                            pyproject_path = project_root / "pyproject.toml"
+                            if pyproject_path.exists():
+                                with open(pyproject_path, "rb") as f:
+                                    data = tomllib.load(f)
+                                    package_name_for_registry = data.get("project", {}).get("name")
+                        except Exception:
+                            pass
+                    
+                    resolved_version, error_details = resolve_version_via_semantic_release(
+                        project_root,
+                        subfolder_path=None,
+                        package_name=package_name_for_registry,
+                        repository=repository,
+                        repository_url=repository_url,
+                    )
 
                 if resolved_version:
                     print(f"Resolved version via semantic-release: {resolved_version}")
@@ -319,8 +455,11 @@ def main() -> int:
                         "This could mean:\n"
                         "  - No release is needed (no relevant commits)\n"
                         "  - semantic-release is not installed or configured\n"
-                        "  - Node.js is not available\n\n"
-                        "Please either:\n"
+                    )
+                    if error_details:
+                        error_msg += f"\nDetails: {error_details}\n"
+                    error_msg += (
+                        "\nPlease either:\n"
                         "  - Install semantic-release: npm install -g semantic-release"
                     )
                     if is_subfolder: