chore: add sample update workflow

[ymc9]

Summary by CodeRabbit

• Chores
  • Implemented automated workflow to synchronize sample repositories with the latest package releases upon version publication.

[coderabbitai]

Walkthrough

A new GitHub Actions workflow is introduced that automatically updates sample repositories from the zenstackhq organization. The workflow triggers on release publication or manual dispatch, discovers repositories with the v3-sample topic, updates @zenstackhq packages to their next version, runs code generation, and commits any resulting changes.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow .github/workflows/update-samples.yml	New workflow for automated sample repository updates. Retrieves public repos from zenstackhq organization tagged with v3-sample topic, updates @zenstackhq packages to @next version, executes code generation, and commits changes with conditional logic based on package.json presence and available packages. Uses dynamic matrix for per-repo processing.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Dynamic matrix job orchestration: Verify proper matrix variable passing from discovery job to processing job and correct string interpolation in matrix context.
• GitHub API GraphQL query: Confirm the query correctly retrieves public repositories with the specified topic filter and produces expected JSON structure.
• Package enumeration logic: Validate that the script correctly parses and iterates over @zenstackhq scoped packages from both dependencies and devDependencies sections.
• Commit and push conditions: Review conditional logic to ensure commits only occur when changes exist and that the standardized commit message format is correctly formatted.
• Authentication and credentials: Verify proper PAT usage for repository checkout and commit operations.

Poem

🐰 A workflow hops through every repo so fine,
Updating packages in the zenstackhq line,
Code generation spins with each release,
Sample repos update with automated ease,
✨ Changes committed, the pipeline's divine!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "chore: add sample update workflow" directly and accurately reflects the primary change in the changeset. The PR introduces a new GitHub Actions workflow file that automates updating sample repositories under the zenstackhq organization. The title is concise, specific, and uses appropriate semantic versioning conventions with the "chore:" prefix. A teammate scanning the git history would immediately understand that this PR adds a workflow for updating samples, which aligns perfectly with the actual implementation.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/sample-update-wf

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude finished @ymc9's task —— View job

---

PR Review: Sample Update Workflow

I've reviewed the GitHub Actions workflow for updating sample repositories. Here's my comprehensive feedback:

Todo List:

• Read and analyze the workflow file
• Evaluate code quality and GitHub Actions best practices
• Check for security concerns
• Assess performance considerations
• Provide comprehensive feedback

---

Code Quality & Best Practices ✅

Strengths:

• Well-structured workflow with clear job separation
• Good use of matrix strategy for parallel processing
• Proper conditional execution with if statements
• Clean variable naming and organization
• Good use of outputs to pass data between jobs

Minor improvements:

• Consider adding workflow description/comments at the top
• The workflow name could be more descriptive: "Update ZenStack Sample Repositories"

Security Assessment ⚠️

Concerns identified:

1. PAT Token Usage (.github/workflows/update-samples.yml:21, 53)

   • Uses secrets.PAT_TOKEN which likely has broad permissions
   • Consider using GitHub's built-in GITHUB_TOKEN with appropriate permissions instead
   • If PAT is required, ensure it has minimal necessary scopes

2. Git Configuration (.github/workflows/update-samples.yml:104-105)

   • Uses generic bot email/name - consider using a more specific identity
   • No verification of commit signing

Recommendations:

permissions:
  contents: read
  # Add specific permissions needed for the workflow

Potential Bugs & Issues 🐛

1. Command Typo (.github/workflows/update-samples.yml:99)

   npx zen generate  # Should be 'zenstack generate'

2. Error Handling

   • No error handling for failed package updates
   • Missing validation that packages were actually updated
   • No rollback mechanism if updates fail

3. Race Conditions

   • Multiple repos could be updated simultaneously, potentially causing conflicts
   • No mechanism to handle partial failures

Performance Considerations 🚀

Good practices:

• Uses fail-fast: false to continue processing other repos if one fails
• Efficient use of GitHub CLI and jq for repo discovery
• Caches Node.js dependencies appropriately

Potential optimizations:

• Consider adding timeout limits for long-running operations
• Could benefit from caching jq/gh CLI tools
• Large organizations might hit rate limits (currently limited to 100 repos)

Functionality Review 📋

Logic Flow:

1. ✅ Discovers repos with v3-sample topic
2. ✅ Creates matrix for parallel processing
3. ✅ Checks for Node.js projects
4. ✅ Updates ZenStack packages to next tag
5. ⚠️ Runs generation command (with typo)
6. ✅ Commits and pushes changes

Edge Cases Handled:

• ✅ Repos without package.json
• ✅ Repos with no ZenStack packages
• ✅ No changes to commit
• ❌ Network failures during npm install
• ❌ Invalid package.json format

Test Coverage 🧪

Missing:

• No integration tests for the workflow
• No validation of the update process
• Consider adding a dry-run mode for testing

Recommended Fixes

1. Fix the command typo:

- npx zenstack generate  # Fix: zen -> zenstack

2. Add error handling:

- name: Update @zenstackhq packages to next
  run: |
    set -e  # Exit on any error
    # ... existing logic

3. Consider using GITHUB_TOKEN instead of PAT if possible:

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Overall Assessment

This is a well-designed workflow that serves its purpose effectively. The main issues are:

• A critical typo in the zenstack command
• Security considerations around PAT token usage
• Missing error handling for edge cases

The workflow demonstrates good understanding of GitHub Actions patterns and should work reliably once the typo is fixed.

Recommendation: Approve with requested changes - Fix the command typo before merging.

---

[Copilot]

Pull Request Overview

This PR adds a new GitHub Actions workflow to automatically update @zenstackhq packages to the next release tag across all sample repositories in the zenstackhq organization. The workflow triggers on releases or manual dispatch and uses repository topics to identify target repositories.

• Adds automation to keep sample repos in sync with latest package releases
• Uses GitHub API to discover repos tagged with v3-sample topic
• Updates packages via npm and commits changes back to each sample repository

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

.github/workflows/update-samples.yml (3)

8-9: Update permissions to allow write access for commit and push operations.

The workflow declares contents: read but performs write operations (commit and push) via PAT_TOKEN. While the PAT bypasses workflow permissions, this creates confusion and doesn't accurately reflect the workflow's requirements.

Clarify the permissions declaration:

 permissions:
-    contents: read
+    contents: write

Alternatively, if you prefer explicit documentation that PAT_TOKEN overrides permissions, add a comment.

---

75-82: Handle potential null values in jq filter for robust package extraction.

The jq filter uses add on [.dependencies, .devDependencies] (line 77), but if either key is missing or null in package.json, this could fail or produce unexpected results.

Apply this diff to safely handle missing fields:

                   # Get all @zenstackhq packages in the repo
-                  PACKAGES=$(cat package.json | jq -r '
+                  PACKAGES=$(cat package.json | jq -r '
                     [.dependencies, .devDependencies] |
-                    add |
+                    map(select(. != null)) | add // {} |
                     to_entries |
                     map(select(.key | startswith("@zenstackhq/"))) |
                     map(.key) |
                     .[]
                   ')

---

39-46: Consider fail-fast strategy implications and add logging for debugging.

The fail-fast: false setting (line 46) means failures in one repo won't stop updates to others, which is reasonable for batch operations. However, if updates fail silently (before error handling fixes), failures could go unnoticed.

Once error handling is added to the update steps, consider adding a summary step that reports successes and failures across all repos for better visibility.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 02a621a and dc82525.

📒 Files selected for processing (1)

• .github/workflows/update-samples.yml (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: build-test (20.x, sqlite)
• GitHub Check: build-test (20.x, postgresql)
• GitHub Check: claude-review