feat: Add ops endpoints and refactor sync workflow #284
Conversation
WalkthroughIntroduces a multi-stage GitHub Actions workflow to sync docs from a source repo, aggregate results, generate docs, and create a PR. Adds a composite action for file syncing with config handling, several helper scripts, new API docs content and metadata (including Ops), template-driven API doc generation, and updates examples/README. Removes a test script. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Trigger as Workflow Trigger
participant Prepare as Job: Prepare
participant Sync as Job: Sync Files (matrix)
participant Agg as Job: Aggregate Results
participant Docs as Job: Generate Docs
participant PR as Job: Create PR
participant Sum as Job: Summary
participant Clean as Job: Cleanup
Trigger->>Prepare: Start (version, paths)
Note over Prepare: Detect/validate version<br/>Set outputs
Prepare-->>Sync: needs.version
par Matrix types
Sync->>Sync: Set params per type<br/>(changelog/config/api_gen/api_debug/api_ops)
Sync->>Action: Use composite sync-files
Action->>Action: Optional config temp + sanitize
Action->>Action: Run sync.sh (filter/exclude)
Action-->>Sync: Outputs + artifacts
end
Sync-->>Agg: sync report artifacts
Agg->>Agg: Parse reports, sum totals
Agg-->>Docs: totals, reports
Docs->>Docs: run_doc_generation()
Docs-->>PR: generation_success, totals
PR->>PR: create/update PR (gh)
PR-->>Sum: pr_url
Sum->>Sum: Print workflow summary
Sum-->>Clean: done
Clean->>Clean: Delete artifacts (if enabled)
sequenceDiagram
autonumber
participant Wf as Workflow Step
participant Act as Composite Action (sync-files)
participant SH as sync.sh
Wf->>Act: inputs(type,title,source_path,target_path,filter,exclude,sanitize_script)
alt type == "config"
Act->>Act: Prepare config temp dir
Act->>Act: Copy source to temp config.yaml
Act->>Act: Run sanitize script (if present)
end
Act->>SH: TYPE, TITLE, SOURCE_PATH, TARGET_PATH, FILTER, EXCLUDE
SH->>SH: Single-file or directory sync<br/>Collect added/updated/deleted
SH-->>Act: added, updated, deleted, total + artifacts
Act-->>Wf: outputs(added,updated,deleted,total)
opt Cleanup
Act->>Act: Remove temp config dir
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60–90 minutes Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches
🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for genlayer-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
dohernandez
force-pushed
the
feat/nod-369-document-ops-rpc-endpoint
branch
5 times, most recently
from
a9dc144 to
af62c64
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
dohernandez
force-pushed
the
feat/nod-369-document-ops-rpc-endpoint
branch
from
0f1ca5a to
b885fc1
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
…-docs-from-node.yml
…types in sync-docs-from-node.yml
… in sync-docs-from-node.yml
…ync-docs-from-node.yml
…d ops files in sync-docs-from-node.yml
…cleanup of artifacts
dohernandez
force-pushed
the
feat/nod-369-document-ops-rpc-endpoint
branch
from
6d3ca3d to
af43272
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (9)
.github/scripts/sync-artifact-files.sh (1)
45-47: Add hard safety guards around rsync --delete (and support dry-run).Unprotected --delete can wipe large portions of the repo if TARGET_ROOT or path resolution is wrong (empty, "/", ".", etc.). Add explicit validations and an opt-in for destructive deletes; also expose a dry-run mode.
- # Always run rsync with delete to ensure stale files are removed even when source is empty - rsync -av --delete "$source_path/" "$target_path/" + # Safety checks before destructive sync + if [[ -z "$TARGET_ROOT" || "$TARGET_ROOT" == "/" ]]; then + echo "Refusing to sync to an unsafe TARGET_ROOT: '$TARGET_ROOT'" >&2 + exit 1 + fi + if [[ -z "$path" || "$path" == "/" ]]; then + echo "Refusing to sync an unsafe path value: '$path'" >&2 + exit 1 + fi + # If syncing directly to the repo root (.), require explicit opt-in + if [[ "$TARGET_ROOT" == "." && "${FORCE_RSYNC_DELETE:-0}" != "1" ]]; then + echo "Refusing to run rsync --delete to '.' without FORCE_RSYNC_DELETE=1" >&2 + exit 1 + fi + # Optional dry run: RSYNC_DRY_RUN=1 previews deletions/changes + RSYNC_FLAGS=(-av --delete) + if [[ "${RSYNC_DRY_RUN:-0}" == "1" ]]; then + RSYNC_FLAGS+=(-n) + echo "Note: Running rsync in dry-run mode (RSYNC_DRY_RUN=1)" + fi + rsync "${RSYNC_FLAGS[@]}" "$source_path/" "$target_path/".github/actions/sync-files/sync.sh (1)
89-90: Fix trap quoting (SC2064) to avoid early expansion.Ensure the temp directory path is expanded at signal time, not at definition.
- trap "rm -rf $TEMP_SOURCE" EXIT + trap 'rm -rf "$TEMP_SOURCE"' EXIT.github/workflows/sync-docs-from-node.yml (7)
350-433: Quote $GITHUB_OUTPUT when exporting pr_url; also export when updating existing PR.Prevents shellcheck warnings and ensures the summary can always read
pr_url.- echo "pr_url=$PR_URL" >> $GITHUB_OUTPUT + echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT" @@ - echo "pr_url=$PR_URL" >> $GITHUB_OUTPUT + echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT"
56-66: Fix version extraction fallbacks and quote $GITHUB_OUTPUT.Use chained ternaries; quote $GITHUB_OUTPUT to avoid word-splitting (shellcheck SC2086).
- - name: Extract version parameter + - name: Extract version parameter id: extract run: | - if [ "${{ github.event_name }}" = "repository_dispatch" ]; then - VERSION="${{ github.event.client_payload.version || 'latest' }}" + if [ "${{ github.event_name }}" = "repository_dispatch" ]; then + VERSION="${{ github.event.client_payload.version != '' && github.event.client_payload.version || 'latest' }}" else - VERSION="${{ github.event.inputs.version || 'latest' }}" + VERSION="${{ github.event.inputs.version != '' && github.event.inputs.version || 'latest' }}" fi - echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "version=$VERSION" >> "$GITHUB_OUTPUT" echo "Requested version: $VERSION"
67-76: Token fallback and output quoting in “Detect latest version”.Select a token via ternary (not
||), and quote $GITHUB_OUTPUT.- name: Detect latest version id: detect if: steps.extract.outputs.version == 'latest' env: - GITHUB_TOKEN: ${{ secrets.NODE_REPO_TOKEN || secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ secrets.NODE_REPO_TOKEN != '' && secrets.NODE_REPO_TOKEN || secrets.GITHUB_TOKEN }} run: | source .github/scripts/version-utils.sh LATEST_TAG=$(detect_latest_version "$GITHUB_TOKEN") echo "Latest version detected: $LATEST_TAG" - echo "version=$LATEST_TAG" >> $GITHUB_OUTPUT + echo "version=$LATEST_TAG" >> "$GITHUB_OUTPUT"
108-120: Use valid token fallback for source checkout.Avoid
||in expressions; prefer ternary. This ensures a valid token string is passed to actions/checkout.- name: Clone source repository uses: actions/checkout@v4 with: repository: genlayerlabs/genlayer-node - token: ${{ secrets.NODE_REPO_TOKEN || secrets.GITHUB_TOKEN }} + token: ${{ secrets.NODE_REPO_TOKEN != '' && secrets.NODE_REPO_TOKEN || secrets.GITHUB_TOKEN }} fetch-depth: 1 sparse-checkout: | docs configs/node/config.yaml.example sparse-checkout-cone-mode: true path: source-repo ref: ${{ needs.prepare.outputs.version }}
121-156: Harden parameter derivation: replace all||fallbacks and quote outputs.These outputs drive the composite action; with
||you risk booleans and broken paths/regexes. Also quote $GITHUB_OUTPUT everywhere (SC2086).- name: Set sync parameters id: set_params run: | case "${{ matrix.sync_type }}" in "changelog") - echo "title=Changelog" >> $GITHUB_OUTPUT - echo "source_path=source-repo/${{ github.event.inputs.changelog_path || github.event.client_payload.changelog_path || 'docs/changelog' }}" >> $GITHUB_OUTPUT - echo "target_path=content/validators/changelog" >> $GITHUB_OUTPUT - echo "filter_pattern=.*" >> $GITHUB_OUTPUT + echo "title=Changelog" >> "$GITHUB_OUTPUT" + echo "source_path=source-repo/${{ github.event.inputs.changelog_path != '' && github.event.inputs.changelog_path || (github.event.client_payload.changelog_path != '' && github.event.client_payload.changelog_path || 'docs/changelog') }}" >> "$GITHUB_OUTPUT" + echo "target_path=content/validators/changelog" >> "$GITHUB_OUTPUT" + echo "filter_pattern=.*" >> "$GITHUB_OUTPUT" ;; "config") - echo "title=Config File" >> $GITHUB_OUTPUT - echo "source_path=source-repo/configs/node/config.yaml.example" >> $GITHUB_OUTPUT - echo "target_path=content/validators/config.yaml" >> $GITHUB_OUTPUT - echo "filter_pattern=.*" >> $GITHUB_OUTPUT - echo "sanitize_script=.github/scripts/sanitize-config.sh" >> $GITHUB_OUTPUT + echo "title=Config File" >> "$GITHUB_OUTPUT" + echo "source_path=source-repo/configs/node/config.yaml.example" >> "$GITHUB_OUTPUT" + echo "target_path=content/validators/config.yaml" >> "$GITHUB_OUTPUT" + echo "filter_pattern=.*" >> "$GITHUB_OUTPUT" + echo "sanitize_script=.github/scripts/sanitize-config.sh" >> "$GITHUB_OUTPUT" ;; "api_gen") - echo "title=API Gen Methods" >> $GITHUB_OUTPUT - echo "source_path=source-repo/${{ github.event.inputs.api_gen_path || github.event.client_payload.api_gen_path || 'docs/api/rpc' }}" >> $GITHUB_OUTPUT - echo "target_path=pages/api-references/genlayer-node/gen" >> $GITHUB_OUTPUT - echo "filter_pattern=${{ github.event.inputs.api_gen_regex || github.event.client_payload.api_gen_regex || 'gen_(?!dbg_).*' }}" >> $GITHUB_OUTPUT + echo "title=API Gen Methods" >> "$GITHUB_OUTPUT" + echo "source_path=source-repo/${{ github.event.inputs.api_gen_path != '' && github.event.inputs.api_gen_path || (github.event.client_payload.api_gen_path != '' && github.event.client_payload.api_gen_path || 'docs/api/rpc') }}" >> "$GITHUB_OUTPUT" + echo "target_path=pages/api-references/genlayer-node/gen" >> "$GITHUB_OUTPUT" + echo "filter_pattern=${{ github.event.inputs.api_gen_regex != '' && github.event.inputs.api_gen_regex || (github.event.client_payload.api_gen_regex != '' && github.event.client_payload.api_gen_regex || 'gen_(?!dbg_).*') }}" >> "$GITHUB_OUTPUT" ;; "api_debug") - echo "title=API Debug Methods" >> $GITHUB_OUTPUT - echo "source_path=source-repo/${{ github.event.inputs.api_debug_path || github.event.client_payload.api_debug_path || 'docs/api/rpc' }}" >> $GITHUB_OUTPUT - echo "target_path=pages/api-references/genlayer-node/debug" >> $GITHUB_OUTPUT - echo "filter_pattern=${{ github.event.inputs.api_debug_regex || github.event.client_payload.api_debug_regex || 'gen_dbg_.*' }}" >> $GITHUB_OUTPUT + echo "title=API Debug Methods" >> "$GITHUB_OUTPUT" + echo "source_path=source-repo/${{ github.event.inputs.api_debug_path != '' && github.event.inputs.api_debug_path || (github.event.client_payload.api_debug_path != '' && github.event.client_payload.api_debug_path || 'docs/api/rpc') }}" >> "$GITHUB_OUTPUT" + echo "target_path=pages/api-references/genlayer-node/debug" >> "$GITHUB_OUTPUT" + echo "filter_pattern=${{ github.event.inputs.api_debug_regex != '' && github.event.inputs.api_debug_regex || (github.event.client_payload.api_debug_regex != '' && github.event.client_payload.api_debug_regex || 'gen_dbg_.*') }}" >> "$GITHUB_OUTPUT" ;; "api_ops") - echo "title=API Ops Methods" >> $GITHUB_OUTPUT - echo "source_path=source-repo/${{ github.event.inputs.api_ops_path || github.event.client_payload.api_ops_path || 'docs/api/ops' }}" >> $GITHUB_OUTPUT - echo "target_path=pages/api-references/genlayer-node/ops" >> $GITHUB_OUTPUT - echo "filter_pattern=.*" >> $GITHUB_OUTPUT + echo "title=API Ops Methods" >> "$GITHUB_OUTPUT" + echo "source_path=source-repo/${{ github.event.inputs.api_ops_path != '' && github.event.inputs.api_ops_path || (github.event.client_payload.api_ops_path != '' && github.event.client_payload.api_ops_path || 'docs/api/ops') }}" >> "$GITHUB_OUTPUT" + echo "target_path=pages/api-references/genlayer-node/ops" >> "$GITHUB_OUTPUT" + echo "filter_pattern=.*" >> "$GITHUB_OUTPUT" ;; esac
41-44: Replace||coalescing in concurrency group with chained ternaries (prevents boolean coercion).GitHub Actions expressions don’t support JS-style
||for string coalescing. This can yield a boolean instead of the intended string and break concurrency grouping.Apply:
concurrency: - group: sync-docs-${{ github.ref }}-${{ github.event.inputs.version || github.event.client_payload.version || 'latest' }} + group: sync-docs-${{ github.ref }}-${{ github.event.inputs.version != '' && github.event.inputs.version || (github.event.client_payload.version != '' && github.event.client_payload.version || 'latest') }} cancel-in-progress: true
329-348: Emithas_changesoutput in thecheck_changesstepThe
create_prjob is gated onsteps.check_changes.outputs.has_changes, but thecheck_changesstep never emits that output. Please update the workflow to sethas_changesfor both branches of the condition:Suggested diff for
.github/workflows/sync-docs-from-node.yml:- name: Check for changes and create branch id: check_changes run: | source .github/scripts/git-utils.sh - if check_for_changes; then + if check_for_changes; then + echo "has_changes=true" >> "$GITHUB_OUTPUT" BRANCH_NAME=$(create_sync_branch "${{ needs.prepare.outputs.version }}") # Use aggregated metrics from aggregate-results job commit_and_push_changes \ "${{ needs.prepare.outputs.version }}" \ "${{ needs.aggregate-results.outputs.total_changes }}" \ "${{ needs.aggregate-results.outputs.total_added }}" \ "${{ needs.aggregate-results.outputs.total_updated }}" \ "${{ needs.aggregate-results.outputs.total_deleted }}" \ "$BRANCH_NAME" else - echo "No changes to commit" - exit 0 + echo "No changes to commit" + echo "has_changes=false" >> "$GITHUB_OUTPUT" + exit 0 fi• Verified that
git-utils.shalready uses selective staging via
git add --all content/validators pages/api-references pages/validators(line 47), so no changes are needed there.
🧹 Nitpick comments (23)
content/api-references/genlayer-node/content.mdx (7)
11-13: Add a caution that Debug methods shouldn’t be enabled in production.A short warning helps users avoid exposing debug surfaces on public nodes.
Apply this diff to add the note:
These methods are available for debugging and testing purposes during development. + +> Note: Debug endpoints should be disabled on production/public nodes. They may expose internal state or increase attack surface.
17-25: Clarify Ethereum compatibility and include raw-transaction send.Listing
eth_sendRawTransactionprevents confusion whereeth_sendTransactionrequires an unlocked account. Also small copy edits.Apply this diff:
-The GenLayer Node also supports Ethereum-compatible methods that are proxied to the underlying infrastructure. These methods follow the standard [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`. +The GenLayer Node supports Ethereum-compatible methods proxied to the underlying infrastructure. These follow the [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`. @@ - `eth_sendTransaction` +- `eth_sendRawTransaction` - `eth_call` - And other standard Ethereum JSON-RPC methods + +> Note: `eth_sendTransaction` requires an unlocked account on the node. Most deployments use `eth_sendRawTransaction` with locally signed transactions.
47-60: Use distinct addresses and clarify target is the contract address.Using identical
from/tocan confuse readers. Suggest a clear ERC-20balanceOf(address)read example with different addresses and a brief hint.Apply this diff:
-# Execute a contract call +# Execute a contract call (read-only) @@ - -d '{ + -d '{ "jsonrpc": "2.0", "method": "gen_call", "params": [{ - "from": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6", - "to": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6", - "data": "0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d4c9db96c4b4d8b6", + "from": "0x1111111111111111111111111111111111111111", // caller (arbitrary EOA) + "to": "0x2222222222222222222222222222222222222222", // token contract + "data": "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", // balanceOf(0xaaaa...) "type": "read", "transaction_hash_variant": "latest-nonfinal" }], "id": 1 }'
62-73: The long base64 payload hurts scannability; consider collapsing or replacing with a placeholder.Readers only need to know the param shape. Collapsing improves readability without losing value.
Apply this diff (uses MDX-friendly details):
-# Get contract schema +# Get contract schema @@ - -d '{ + -d '{ "jsonrpc": "2.0", "method": "gen_getContractSchema", "params": [{ - "code": "IyB7ICJEZXBlbmRzIjogInB5LWdlbmxheWVyOnRlc3QiIH0KCmZyb20gZ2VubGF5ZXIgaW1wb3J0ICoKCgojIGNvbnRyYWN0IGNsYXNzCmNsYXNzIFN0b3JhZ2UoZ2wuQ29udHJhY3QpOgogICAgc3RvcmFnZTogc3RyCgogICAgIyBjb25zdHJ1Y3RvcgogICAgZGVmIF9faW5pdF9fKHNlbGYsIGluaXRpYWxfc3RvcmFnZTogc3RyKToKICAgICAgICBzZWxmLnN0b3JhZ2UgPSBpbml0aWFsX3N0b3JhZ2UKCiAgICAjIHJlYWQgbWV0aG9kcyBtdXN0IGJlIGFubm90YXRlZCB3aXRoIHZpZXcKICAgIEBnbC5wdWJsaWMudmlldwogICAgZGVmIGdldF9zdG9yYWdlKHNlbGYpIC0+IHN0cjoKICAgICAgICByZXR1cm4gc2VsZi5zdG9yYWdlCgogICAgIyB3cml0ZSBtZXRob2QKICAgIEBnbC5wdWJsaWMud3JpdGUKICAgIGRlZiB1cGRhdGVfc3RvcmFnZShzZWxmLCBuZXdfc3RvcmFnZTogc3RyKSAtPiBOb25lOgogICAgICAgIHNlbGYuc3RvcmFnZSA9IG5ld19zdG9yYWdlCg==" + "code": "<base64-encoded contract source>" }], "id": 1 }' + +<details> +<summary>Why base64?</summary> +Some environments require embedding the source inline. Use base64 to avoid JSON escaping issues. Large inputs can be provided via file upload or URL if supported by your node build. +</details>
37-37: Use 127.0.0.1 to avoid IPv6 resolution quirks with curl on some systems.Minor, but avoids occasional issues where
localhostresolves to::1.Apply this diff:
-curl -X POST http://localhost:9151 \ +curl -X POST http://127.0.0.1:9151 \Also applies to: 47-47, 63-63, 75-75, 88-88
100-103: State the ops_ prefix and scope.Make it explicit that Ops methods use the
ops_prefix and are geared for health/metrics/maintenance.Apply this diff:
-These methods provide operational endpoints for monitoring the GenLayer node. +These methods provide operational endpoints (health, metrics, maintenance) for monitoring the GenLayer node. Ops methods are prefixed with `ops_`.
7-7: Confirm safe template interpolation & Node.js support
- The generator (
scripts/generate-api-docs.js) reads the MDX template and uses literalString.prototype.replacecalls to inject content:
.replace('${genMethods.join(\'\\n\\n\')}', genMethods.join('\n\n')), and similarly fordebugMethodsandopsMethods.- No use of
eval,new Function, orvm.runInNewContextwas found in the script.- CI is configured via
actions/setup-node@v4withnode-version: '20', which fully supports modern JS syntax (including optional chaining).- The only occurrences of these placeholders are in
content/api-references/genlayer-node/content.mdxat lines 7, 13, and 104.Optional refactor recommendation:
- To remove raw JS interpolation from the MDX templates, you could pre-join the method strings in the generator and expose them as single variables, or adopt a dedicated templating engine (e.g., Mustache/Handlebars) for clearer separation between content and code.
.github/scripts/sync-artifact-files.sh (2)
2-2: Enable stricter bash error handling.Use nounset and pipefail for better CI robustness.
-set -e +set -euo pipefail
31-33: Validate each sync path is relative and normalized.Guard against absolute paths or path traversal in SYNC_PATHS to avoid syncing outside the repo.
- source_path="$SOURCE_ROOT/$path" - target_path="$TARGET_ROOT/$path" + # Reject absolute or traversal paths + if [[ "$path" = /* || "$path" == *".."* ]]; then + echo " ⛔ Invalid path (must be relative, no '..'): $path" >&2 + continue + fi + source_path="$SOURCE_ROOT/$path" + target_path="$TARGET_ROOT/$path"To verify nothing unsafe slips through, run a quick grep in the workflow that calls this script to list all provided paths are relative.
Also applies to: 38-40
.github/actions/sync-files/sync.sh (2)
1-2: Harden shell options for reliability.Adopt nounset and pipefail to fail fast on unset vars and pipeline errors.
-#!/bin/bash -set -e +#!/bin/bash +set -euo pipefail
35-49: Guarantee PCRE support even when Perl is missing.Current fallback to grep -E will mis-evaluate PCRE patterns (e.g., negative lookahead). Prefer grep -P when available before falling back to Perl, and emit a clear error if neither exists.
-# Check if filename matches pattern -matches_pattern() { +matches_pattern() { local filename="$1" local pattern="$2" - - # Try perl first (supports PCRE including negative lookahead) - if command -v perl >/dev/null 2>&1; then + # Prefer grep -P, then perl; error otherwise + if command -v grep >/dev/null 2>&1 && grep -P "" </dev/null >/dev/null 2>&1; then + echo "$filename" | grep -qP -- "^(${pattern})$" + return $? + elif command -v perl >/dev/null 2>&1; then echo "$filename" | perl -ne "exit 0 if /^($pattern)\$/; exit 1" return $? fi - - # Fallback to grep -E (doesn't support negative lookahead) - echo "$filename" | grep -E "^($pattern)$" >/dev/null 2>&1 - return $? + echo "ERROR: No PCRE-capable engine (grep -P or perl) available for pattern: $pattern" >&2 + return 2 }Optionally add a quick self-check in the workflow runner to confirm grep -P availability.
.github/workflows/README.md (3)
31-35: Clarify PCRE dependency for regex filtering.State that PCRE evaluation requires grep -P or Perl on the runner; otherwise filters degrade or error.
-- Regex filtering uses Perl-compatible patterns (supports negative lookahead) +- Regex filtering uses Perl-compatible patterns (supports negative lookahead). Requires a PCRE-capable engine on the runner (grep -P or Perl).
141-155: Add a language to fenced code block to satisfy markdownlint (MD040).Use text for the ASCII diagram.
-``` +```text prepare (version detection) ↓ sync-files (matrix: 5 parallel jobs) ↓ aggregate-results (merges artifacts) ↓ generate-docs (runs npm scripts) ↓ create-pr (commits & creates PR) ↓ summary (always runs, shows results) ↓ cleanup (removes all artifacts if enabled)--- `198-202`: **Scope and safety note for rsync deletions.** Since deletions use rsync --delete, add a one-line note that the script validates/guards target directories to prevent accidental mass deletion. This aligns with the safety checks added in sync-artifact-files.sh. </blockquote></details> <details> <summary>.github/scripts/sanitize-config.sh (1)</summary><blockquote> `26-33`: **Surface Python sanitization as optional but fail on Python errors.** Given set -e is on, a failing sanitize-config.py will stop the workflow—which is desirable. Consider echoing which steps ran for better logs. ```diff if [[ -f "$SCRIPT_DIR/sanitize-config.py" ]]; then - python3 "$SCRIPT_DIR/sanitize-config.py" "$CONFIG_FILE" + echo "Running Python sanitization (remove node.dev sections)..." + python3 "$SCRIPT_DIR/sanitize-config.py" "$CONFIG_FILE" else echo "Warning: sanitize-config.py not found, skipping Python sanitization" fi.github/actions/sync-files/action.yml (4)
25-27: Clarify when sanitize_script runs.It runs before sync for type=config; the current description suggests “after sync”.
sanitize_script: - description: 'Optional script path to run after sync (for sanitization/post-processing)' + description: 'Optional script to pre-process source (used before sync for type=config)' required: false default: ''
78-84: Defensive shell options in step to fail fast.Guard the step with stricter bash options.
- run: | - # Use prepared config source if it's a config type, otherwise use original source + run: | + set -euo pipefail + # Use prepared config source if it's a config type, otherwise use original source
85-92: Remove trailing spaces and ensure newline at EOF (yamllint).Trailing spaces on these lines and missing newline at EOF trip linting.
- ${{ github.action_path }}/sync.sh \ + ${{ github.action_path }}/sync.sh \ "${{ inputs.type }}" \ "${{ inputs.title }}" \ "$SOURCE_PATH" \ "${{ inputs.target_path }}" \ "${{ inputs.filter_pattern }}" \ "${{ inputs.exclude_files }}" @@ - retention-days: 1 + retention-days: 1 +Also applies to: 100-100
44-72: Config prep is solid; minor portability nit.Consider quoting $GITHUB_ENV on writes and echoing explicit status messages to aid troubleshooting; functional behavior looks correct.
.github/workflows/sync-docs-from-node.yml (4)
78-87: Quote $GITHUB_OUTPUT in “Set final version”.Minor shellcheck fix; prevents word-splitting.
- echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "version=$VERSION" >> "$GITHUB_OUTPUT"
441-519: Summary parsing looks consistent with artifact layout. Consider minor robustness.You already point to artifacts/sync-reports. Optional: tolerate “Summary:” format too and guard greps with quotes to avoid globbing. Not blocking.
542-571: Quote $GITHUB_OUTPUT and tidy multi-line output (shellcheck SC2086/SC2129).Safer redirection when writing outputs; reduces shellcheck noise.
- name: Check cleanup configuration id: check run: | if [[ "${{ env.CLEANUP_ARTIFACTS }}" == "true" ]]; then - echo "should_cleanup=true" >> $GITHUB_OUTPUT + echo "should_cleanup=true" >> "$GITHUB_OUTPUT" echo "✅ Artifact cleanup is enabled" else - echo "should_cleanup=false" >> $GITHUB_OUTPUT + echo "should_cleanup=false" >> "$GITHUB_OUTPUT" echo "⏭️ Artifact cleanup is disabled (CLEANUP_ARTIFACTS=${{ env.CLEANUP_ARTIFACTS }})" fi @@ - echo "artifacts_list<<EOF" >> $GITHUB_OUTPUT - echo "$ARTIFACTS_TO_DELETE" | tr '|' '\n' >> $GITHUB_OUTPUT - echo "EOF" >> $GITHUB_OUTPUT + { + echo "artifacts_list<<EOF" + echo "$ARTIFACTS_TO_DELETE" | tr '|' '\n' + echo "EOF" + } >> "$GITHUB_OUTPUT"
1-577: Fix trailing spaces and ensure newline at EOF.Static analysis flags many trailing spaces and missing final newline. Cleaning these reduces churn and avoids lint failures. Functionally no change.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (17)
.github/actions/sync-files/action.yml(1 hunks).github/actions/sync-files/sync.sh(1 hunks).github/scripts/aggregate-reports.sh(1 hunks).github/scripts/doc-generator.sh(1 hunks).github/scripts/git-utils.sh(1 hunks).github/scripts/sanitize-config.sh(1 hunks).github/scripts/sync-artifact-files.sh(1 hunks).github/scripts/test_sanitize_config.py(0 hunks).github/scripts/version-utils.sh(1 hunks).github/workflows/README.md(5 hunks).github/workflows/example-trigger-from-node.yml.example(2 hunks).github/workflows/sync-docs-from-node.yml(2 hunks)content/api-references/genlayer-node/content.mdx(1 hunks)pages/api-references/genlayer-node.mdx(1 hunks)pages/api-references/genlayer-node/_meta.json(1 hunks)pages/api-references/genlayer-node/ops/_meta.json(1 hunks)scripts/generate-api-docs.js(2 hunks)
💤 Files with no reviewable changes (1)
- .github/scripts/test_sanitize_config.py
✅ Files skipped from review due to trivial changes (2)
- pages/api-references/genlayer-node.mdx
- pages/api-references/genlayer-node/ops/_meta.json
🚧 Files skipped from review as they are similar to previous changes (7)
- .github/scripts/doc-generator.sh
- .github/workflows/example-trigger-from-node.yml.example
- .github/scripts/version-utils.sh
- pages/api-references/genlayer-node/_meta.json
- .github/scripts/aggregate-reports.sh
- scripts/generate-api-docs.js
- .github/scripts/git-utils.sh
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: dohernandez
PR: genlayerlabs/genlayer-docs#257
File: .github/workflows/sync-docs-from-node.yml:0-0
Timestamp: 2025-07-26T13:26:45.588Z
Learning: In the sync-docs-from-node.yml workflow, the user prefers selective git staging with `git add content/validators pages/api-references pages/validators` rather than `git add -A` to avoid staging unintended changes, as these are the expected directories to be modified during the documentation sync process.
📚 Learning: 2025-07-26T13:26:45.588Z
Learnt from: dohernandez
PR: genlayerlabs/genlayer-docs#257
File: .github/workflows/sync-docs-from-node.yml:0-0
Timestamp: 2025-07-26T13:26:45.588Z
Learning: In the sync-docs-from-node.yml workflow, the user prefers selective git staging with `git add content/validators pages/api-references pages/validators` rather than `git add -A` to avoid staging unintended changes, as these are the expected directories to be modified during the documentation sync process.
Applied to files:
.github/workflows/sync-docs-from-node.yml.github/workflows/README.md
📚 Learning: 2025-08-19T21:48:24.895Z
Learnt from: epsjunior
PR: genlayerlabs/genlayer-docs#278
File: components/copy-page.tsx:0-0
Timestamp: 2025-08-19T21:48:24.895Z
Learning: In the genlayer-docs project, markdown files are generated during the build process via `npm run sync-mdx`. If markdown generation fails, the entire deployment process fails, ensuring that markdown files will always exist in production environments.
Applied to files:
.github/workflows/README.md
🪛 Shellcheck (0.10.0)
.github/actions/sync-files/sync.sh
[warning] 89-89: Use single quotes, otherwise this expands now rather than when signalled.
(SC2064)
🪛 actionlint (1.7.7)
.github/workflows/sync-docs-from-node.yml
58-58: shellcheck reported issue in this script: SC2086:info:6:28: Double quote to prevent globbing and word splitting
(shellcheck)
72-72: shellcheck reported issue in this script: SC2086:info:4:31: Double quote to prevent globbing and word splitting
(shellcheck)
80-80: shellcheck reported issue in this script: SC2086:info:6:28: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:3:31: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:4:147: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:5:56: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:6:33: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:9:33: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:10:72: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:11:58: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:12:33: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:13:66: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:16:37: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:17:141: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:18:66: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:19:136: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:22:39: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:23:145: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:24:68: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:25:136: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:28:37: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:29:141: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:30:66: Double quote to prevent globbing and word splitting
(shellcheck)
123-123: shellcheck reported issue in this script: SC2086:info:31:33: Double quote to prevent globbing and word splitting
(shellcheck)
355-355: shellcheck reported issue in this script: SC2086:info:64:28: Double quote to prevent globbing and word splitting
(shellcheck)
355-355: shellcheck reported issue in this script: SC2086:info:76:28: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2129:style:1:1: Consider using { cmd1; cmd2; } >> file instead of individual redirects
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:1:42: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:2:12: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:4:32: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:5:74: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:6:85: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:7:81: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:8:86: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:9:85: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:10:12: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:12:37: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:13:12: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:26:24: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:40:34: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:43:68: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:44:74: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:45:74: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:49:20: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:50:146: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:54:20: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:55:150: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:59:20: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:60:150: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:64:35: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:66:14: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:71:31: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:72:67: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:74:26: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:76:51: Double quote to prevent globbing and word splitting
(shellcheck)
452-452: shellcheck reported issue in this script: SC2086:info:78:70: Double quote to prevent globbing and word splitting
(shellcheck)
544-544: shellcheck reported issue in this script: SC2086:info:2:33: Double quote to prevent globbing and word splitting
(shellcheck)
544-544: shellcheck reported issue in this script: SC2086:info:5:34: Double quote to prevent globbing and word splitting
(shellcheck)
558-558: shellcheck reported issue in this script: SC2129:style:8:1: Consider using { cmd1; cmd2; } >> file instead of individual redirects
(shellcheck)
558-558: shellcheck reported issue in this script: SC2086:info:8:31: Double quote to prevent globbing and word splitting
(shellcheck)
558-558: shellcheck reported issue in this script: SC2086:info:9:46: Double quote to prevent globbing and word splitting
(shellcheck)
558-558: shellcheck reported issue in this script: SC2086:info:10:15: Double quote to prevent globbing and word splitting
(shellcheck)
🪛 YAMLlint (1.37.1)
.github/workflows/sync-docs-from-node.yml
[error] 55-55: trailing spaces
(trailing-spaces)
[error] 183-183: trailing spaces
(trailing-spaces)
[error] 198-198: trailing spaces
(trailing-spaces)
[error] 206-206: trailing spaces
(trailing-spaces)
[error] 215-215: trailing spaces
(trailing-spaces)
[error] 218-218: trailing spaces
(trailing-spaces)
[error] 240-240: trailing spaces
(trailing-spaces)
[error] 246-246: trailing spaces
(trailing-spaces)
[error] 307-307: trailing spaces
(trailing-spaces)
[error] 328-328: trailing spaces
(trailing-spaces)
[error] 333-333: trailing spaces
(trailing-spaces)
[error] 336-336: trailing spaces
(trailing-spaces)
[error] 358-358: trailing spaces
(trailing-spaces)
[error] 363-363: trailing spaces
(trailing-spaces)
[error] 377-377: trailing spaces
(trailing-spaces)
[error] 411-411: trailing spaces
(trailing-spaces)
[error] 418-418: trailing spaces
(trailing-spaces)
[error] 430-430: trailing spaces
(trailing-spaces)
[error] 443-443: trailing spaces
(trailing-spaces)
[error] 450-450: trailing spaces
(trailing-spaces)
[error] 455-455: trailing spaces
(trailing-spaces)
[error] 463-463: trailing spaces
(trailing-spaces)
[error] 466-466: trailing spaces
(trailing-spaces)
[error] 477-477: trailing spaces
(trailing-spaces)
[error] 479-479: trailing spaces
(trailing-spaces)
[error] 484-484: trailing spaces
(trailing-spaces)
[error] 490-490: trailing spaces
(trailing-spaces)
[error] 498-498: trailing spaces
(trailing-spaces)
[error] 504-504: trailing spaces
(trailing-spaces)
[error] 509-509: trailing spaces
(trailing-spaces)
[error] 520-520: trailing spaces
(trailing-spaces)
[error] 552-552: trailing spaces
(trailing-spaces)
[error] 565-565: trailing spaces
(trailing-spaces)
[error] 569-569: trailing spaces
(trailing-spaces)
[error] 571-571: trailing spaces
(trailing-spaces)
[error] 577-577: no new line character at the end of file
(new-line-at-end-of-file)
.github/actions/sync-files/action.yml
[error] 52-52: trailing spaces
(trailing-spaces)
[error] 57-57: trailing spaces
(trailing-spaces)
[error] 60-60: trailing spaces
(trailing-spaces)
[error] 66-66: trailing spaces
(trailing-spaces)
[error] 73-73: trailing spaces
(trailing-spaces)
[error] 84-84: trailing spaces
(trailing-spaces)
[error] 92-92: trailing spaces
(trailing-spaces)
[error] 100-100: trailing spaces
(trailing-spaces)
[error] 107-107: no new line character at the end of file
(new-line-at-end-of-file)
🪛 LanguageTool
.github/workflows/README.md
[grammar] ~31-~31: There might be a mistake here.
Context: ...facts when enabled Important Notes: - Both .md and .mdx files are supporte...
(QB_NEW_EN)
[grammar] ~87-~87: There might be a mistake here.
Context: ....g., v0.3.5, or "latest" to auto-detect) - Changelog path (optional, default: `do...
(QB_NEW_EN)
[grammar] ~88-~88: There might be a mistake here.
Context: ...** (optional, default: docs/changelog) - API gen path (optional, default: `docs...
(QB_NEW_EN)
[grammar] ~89-~89: There might be a mistake here.
Context: ...th** (optional, default: docs/api/rpc) - API debug path (optional, default: `do...
(QB_NEW_EN)
[grammar] ~90-~90: There might be a mistake here.
Context: ...th** (optional, default: docs/api/rpc) - API ops path (optional, default: `docs...
(QB_NEW_EN)
[grammar] ~91-~91: There might be a mistake here.
Context: ...th** (optional, default: docs/api/ops) - API gen regex (optional, default: `gen...
(QB_NEW_EN)
[grammar] ~92-~92: There might be a mistake here.
Context: ...** (optional, default: gen_(?!dbg_).*) - API debug regex (optional, default: `g...
(QB_NEW_EN)
[grammar] ~123-~123: There might be a mistake here.
Context: ...ngelog files (default: docs/changelog) - api_gen_path: Path to API gen methods (default: `doc...
(QB_NEW_EN)
[grammar] ~124-~124: There might be a mistake here.
Context: ...PI gen methods (default: docs/api/rpc) - api_debug_path: Path to API debug methods (default: `d...
(QB_NEW_EN)
[grammar] ~125-~125: There might be a mistake here.
Context: ... debug methods (default: docs/api/rpc) - api_ops_path: Path to API ops methods (default: `doc...
(QB_NEW_EN)
[grammar] ~129-~129: There might be a mistake here.
Context: ...en API files (default: gen_(?!dbg_).*) - This default pattern matches files start...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ... debug API files (default: gen_dbg_.*) - This default pattern matches only files ...
(QB_NEW_EN)
[grammar] ~138-~138: There might be a mistake here.
Context: ... Architecture ### Jobs and Dependencies The workflow uses 7 main jobs with the f...
(QB_NEW_EN)
[grammar] ~157-~157: There might be a mistake here.
Context: ...f enabled) ``` ### Global Configuration The workflow uses environment variables ...
(QB_NEW_EN)
[grammar] ~161-~161: There might be a mistake here.
Context: ...essful completion ### Composite Actions The workflow uses composite actions for ...
(QB_NEW_EN)
[grammar] ~175-~175: There might be a mistake here.
Context: ...generation ### Config File Sanitization The config sync process includes automat...
(QB_NEW_EN)
[grammar] ~176-~176: There might be a mistake here.
Context: ...process includes automatic sanitization: 1. URL Replacement: Real URLs replaced wi...
(QB_NEW_EN)
[grammar] ~181-~181: There might be a mistake here.
Context: ...al changes ### Branch Naming Convention Sync branches follow the pattern: `docs/...
(QB_NEW_EN)
[grammar] ~182-~182: There might be a mistake here.
Context: ...ntion Sync branches follow the pattern: docs/node/{version} - Example: docs/node/v0.3.5 - Version sl...
(QB_NEW_EN)
[grammar] ~183-~183: There might be a mistake here.
Context: ...ttern: docs/node/{version} - Example: docs/node/v0.3.5 - Version slashes are replaced with dashes...
(QB_NEW_EN)
[grammar] ~186-~186: There might be a mistake here.
Context: ...shes for safety ### Artifact Management The workflow uses artifacts to pass data...
(QB_NEW_EN)
[style] ~189-~189: ‘merged together’ might be wordy. Consider a shorter alternative.
Context: ...-merged- All synced files and reports merged together -synced-final` - Final artifact with ...
(EN_WORDINESS_PREMIUM_MERGED_TOGETHER)
[grammar] ~192-~192: There might be a mistake here.
Context: ...nd sync reports Artifact Structure: - Each artifact contains: - `sync_report...
(QB_NEW_EN)
[grammar] ~194-~194: There might be a mistake here.
Context: ...e}.md` - Detailed report with file lists - Synced files in their target directory s...
(QB_NEW_EN)
[grammar] ~198-~198: There might be a mistake here.
Context: ...ct for reference Deletion Handling: - Uses rsync --delete for each specific ...
(QB_NEW_EN)
[grammar] ~203-~203: There might be a mistake here.
Context: ...entation content Automatic Cleanup: - All artifacts are automatically deleted ...
(QB_NEW_EN)
[grammar] ~207-~207: There might be a mistake here.
Context: ...ry generation ### Pull Request Behavior - Creates new PR for new versions - Update...
(QB_NEW_EN)
[grammar] ~208-~208: There might be a mistake here.
Context: ...havior - Creates new PR for new versions - Updates existing open PR for same versio...
(QB_NEW_EN)
[grammar] ~209-~209: There might be a mistake here.
Context: ...pdates existing open PR for same version - Automatically labels with "documentation...
(QB_NEW_EN)
[grammar] ~212-~212: There might be a mistake here.
Context: ...and "node" PR Description includes: - Source repository and version - API filt...
(QB_NEW_EN)
[grammar] ~213-~213: There might be a mistake here.
Context: ...ludes**: - Source repository and version - API filter patterns used - Total files c...
(QB_NEW_EN)
[grammar] ~214-~214: There might be a mistake here.
Context: ...y and version - API filter patterns used - Total files changed with breakdown (adde...
(QB_NEW_EN)
[grammar] ~215-~215: There might be a mistake here.
Context: ...d with breakdown (added/updated/deleted) - List of npm scripts that were run - Auto...
(QB_NEW_EN)
[grammar] ~216-~216: There might be a mistake here.
Context: ...ted) - List of npm scripts that were run - Automated checklist confirming successfu...
(QB_NEW_EN)
[grammar] ~219-~219: There might be a mistake here.
Context: ...ng successful sync ### Workflow Summary The summary job generates a comprehensiv...
(QB_NEW_EN)
[grammar] ~220-~220: There might be a mistake here.
Context: ...hensive report in the GitHub Actions UI: - Overall Results: Version and total cha...
(QB_NEW_EN)
[grammar] ~221-~221: There might be a mistake here.
Context: ...sults**: Version and total change counts - Sync Results by Type: For each sync ty...
(QB_NEW_EN)
[grammar] ~222-~222: There might be a mistake here.
Context: ...lts by Type**: For each sync type shows: - Count of added/updated/deleted files -...
(QB_NEW_EN)
[grammar] ~223-~223: There might be a mistake here.
Context: ... - Count of added/updated/deleted files - Detailed file lists (e.g., "Added: gen_c...
(QB_NEW_EN)
[grammar] ~224-~224: There might be a mistake here.
Context: ...file lists (e.g., "Added: gen_call.mdx") - Pull Request Link: Direct link to crea...
(QB_NEW_EN)
[grammar] ~227-~227: There might be a mistake here.
Context: ...PR ### Documentation Generation Scripts After syncing files, the workflow runs t...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
.github/workflows/README.md
141-141: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (6)
content/api-references/genlayer-node/content.mdx (3)
35-45: LGTM: Ping example is clear and minimal.
87-97: Confirm the receipt param name (txId) and value format.Some APIs expect
txHashor a 0x-prefixed 32-byte hash. Please confirm the exact name and format to prevent copy-paste errors from docs.
29-29: Verified: zkSync JSON-RPC docs URL is up-to-date and canonical.The URL
https://docs.zksync.io/zksync-protocol/api/zks-rpccorrectly points to the official zkSync JSON-RPC documentation and does not require any updates. (docs.zksync.io).github/scripts/sanitize-config.sh (1)
21-24: Good anchoring to avoid editing commented keys.The sed expressions correctly skip commented lines and preserve indentation.
.github/workflows/sync-docs-from-node.yml (2)
228-235: Outputs wiring for generate-docs looks good.
steps.generatesetssuccess=trueinto $GITHUB_OUTPUT and your job output reads from it. Node 20 LTS is a good choice in Aug 2025.
291-301: Job permissions scoped correctly for PR creation.Nice principle-of-least-privilege setup for the create-pr job (contents/pull-requests: write). No issues.
| curl -X POST http://localhost:9151 \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "jsonrpc": "2.0", | ||
| "method": "gen_dbg_trie", | ||
| "params": [{ | ||
| "txID": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8", | ||
| "round": 0 | ||
| }], | ||
| "id": 1 | ||
| }' |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Parameter casing inconsistency: txID vs txId.
This example uses txID, while the receipt example uses txId. Pick one consistent casing across all endpoints (and make sure it matches the actual API).
Apply this diff if the canonical field is txId:
- "txID": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8",
+ "txId": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8",🏁 Script executed:
#!/bin/bash
set -e
# Search for txID and txId in the genlayer-node API reference
rg -n "txID" -C2 content/api-references/genlayer-node
rg -n "txId" -C2 content/api-references/genlayer-node
# Search for any txID or txId across all API references for consistency
rg -n "txID" -C2 content/api-references
rg -n "txId" -C2 content/api-references
# Locate the gen_dbg_trie method to see context of its params
rg -n "gen_dbg_trie" -C2 content/api-referencesLength of output: 2343
Unify parameter casing in genlayer-node examples
The gen_dbg_trie example currently uses "txID", while the gen_getTransactionReceipt example uses "txId". The API’s JSON-RPC payload consistently defines this parameter as txId, so we should update the gen_dbg_trie snippet to match.
• File: content/api-references/genlayer-node/content.mdx
• Lines: 79–83
Apply this diff to correct the casing:
- "txID": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8",
+ "txId": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| curl -X POST http://localhost:9151 \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "jsonrpc": "2.0", | |
| "method": "gen_dbg_trie", | |
| "params": [{ | |
| "txID": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8", | |
| "round": 0 | |
| }], | |
| "id": 1 | |
| }' | |
| curl -X POST http://localhost:9151 \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "jsonrpc": "2.0", | |
| "method": "gen_dbg_trie", | |
| "params": [{ | |
| "txId": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8", | |
| "round": 0 | |
| }], | |
| "id": 1 | |
| }' |
🤖 Prompt for AI Agents
In content/api-references/genlayer-node/content.mdx around lines 75 to 85, the
gen_dbg_trie example uses "txID" which is inconsistent with the API's canonical
"txId"; update the JSON-RPC params to use "txId" (same casing as
gen_getTransactionReceipt) so the example matches the API spec and other
examples.
Description
This PR implements support for ops API endpoints following the established pattern of GenLayer Methods and Debug Methods, and comprehensively refactors the GitHub sync workflow for better maintainability. The ops endpoints are integrated into the documentation generation system with proper navigation and template support. Additionally, the monolithic 904-line sync workflow has been refactored into a modular 6-job architecture with extracted utilities and centralized configuration.
Motivation and Context
The documentation needed support for ops endpoints to provide complete API coverage. The existing GitHub workflow was difficult to maintain due to code duplication and monolithic structure. This refactoring maintains 100% functional equivalence while significantly improving code organization and maintainability.
Changes Made
Ops Endpoint Support:
Workflow Architecture:
Types of Changes
Testing
No test files were modified in this PR. The changes maintain existing functionality while improving architecture. The workflow refactoring preserves all original behavior including regex patterns, config sanitization, and PR templates.
Checklist
Impact
Summary by CodeRabbit
New Features
Documentation
Chores