Automated doc/artifact sync pipeline for crowdsplit and contracts releases - #162
Open
adnanhq wants to merge 30 commits into
Open
Automated doc/artifact sync pipeline for crowdsplit and contracts releases#162adnanhq wants to merge 30 commits into
adnanhq wants to merge 30 commits into
Conversation
Rename contracts package to `contracts-sdk`
Release packages
Release v1.1.0: Event Log System, Multicall Utility & Metrics Aggregation
Release packages
Release v1.1.1: updated readme
Release packages
Contracts SDK v1.2
Release packages
feat(payments): expand SDK to cover Crowdsplit staging endpoints
Release packages
feat(ci): add staging sync workflow with issue automation
feat: add countries API service with unit and integration test
[fix]: remove redundant fields from payment method
chore: restrict dependabot to major only updates #137
Release packages
Migrate payments SDK API base URLs to Oak network domain
Release packages
Updated sandbox url and provider registration types
Implements the generate-abis and check-abis stubs and wires them into a repository_dispatch triggered workflow. - contract-map.ts: single source of truth mapping the 8 vendored contracts to their SDK modules, README table rows and docs links. TimeConstrainedPaymentTreasury stays unmapped on purpose, it shares the PaymentTreasury ABI surface. - generate-abis.ts: regenerates contracts/*/abi.ts from a release ABI bundle with canonicalized (sorted) entries and a dependency-free renderer, and writes abi-manifest.json (canonical-JSON sha256 per contract). Change detection is hash-based, so a release with identical ABIs is a no-op instead of a header-churn PR. New unmapped contracts are reported, never auto-added. DataRegistryKeys drift is checked via viem keccak256. - check-abis.ts: manifest mode (offline, runs in CI on every PR) catches hand edits to generated modules; bundle mode diffs the working tree against a release bundle; the seed command bootstraps the manifest from the committed ABIs (tag: sdk-baseline) until the first real release sync records genuine provenance. - update-readme.ts: renders the Available Entities table between AUTOGEN markers from the contract map. - contracts-sync.yml: on a contracts-release-published dispatch (or manual tag), downloads the release bundle, verifies checksums and metadata, regenerates, adds a minor changeset and opens an idempotent human-reviewed PR against develop. A failing typecheck is surfaced as a PR warning instead of blocking the PR. Failures open a deduplicated contracts-sync issue. - 27 unit tests cover canonicalization, rendering, change detection, registry drift and README marker handling.
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…d types layer - scripts/sync-crowdsplit.mjs: bundles the Crowdsplit OpenAPI spec at a stable release tag (redocly version taken from the crowdsplit checkout), snapshots it to packages/payments/openapi/, regenerates the internal src/generated/api.ts via pinned openapi-typescript, computes an endpoint-level diff natively plus an oasdiff changelog and breaking verdict when available, and emits a patch changeset and PR body. Deterministic output (no timestamps), unchanged specs are no-ops, and the working tree is only touched after every generation step succeeds. - crowdsplit-sync.yml: on a crowdsplit-released dispatch (or manual tag), runs the script against a tag checkout and opens an idempotent human-reviewed PR against develop. Breaking releases get the breaking-api-change label and a PR warning. Failures open a deduplicated api-sync issue. The source commit is resolved from the tag checkout, not the dispatch payload. - ci.yml: abis:check drift gate (contracts) and api-types-freshness job (payments) so generated artifacts cannot drift or be hand-edited unnoticed. - Seeded from crowdsplit v2.1.1: spec snapshot, sync metadata (76 endpoints) and generated types. The generated layer is internal only, not exported; services adopt it progressively. Includes a minor changeset for the payments SDK. - backend-sync.yml issue template now mentions the release-time sync PR; generated paths are marked linguist-generated; CLAUDE.md documents the regeneration commands.
adnanhq
force-pushed
the
feat/doc-sync-pipeline
branch
from
July 17, 2026 09:17
90a1c57 to
9194d9c
Compare
- ci.yml: explicit contents: read permissions on the api-types-freshness job. - scripts.test.ts: build DataRegistryKeys.sol fixtures with a helper instead of single-occurrence string replacement on the closing brace.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sets up the automated documentation and artifact sync pipeline. When crowdsplit or contracts publishes a stable release, a workflow here regenerates everything mechanically derivable from the source repo and opens a reviewable PR against develop. Nothing merges automatically.
Contracts track
generate-abis.ts/check-abis.tsstubs.contract-map.tsis the single source of truth mapping the 8 vendored contracts to their SDK modules, README table rows and docs links.contracts-sync.ymllistens for thecontracts-release-publisheddispatch (or a manual tag), downloads the release ABI bundle, verifies its checksums against the dispatch payload, regeneratescontracts/*/abi.ts+abi-manifest.json+ the README entities table, adds a minor changeset and opens a PR on branchsync/contracts-<tag>. Re-runs for the same tag update the same PR.abis:checkstep: generated ABI modules that were hand-edited or drifted from the manifest fail every PR. The manifest is seeded from the current committed ABIs (tag: sdk-baseline), so the first real contracts release will produce a large sync PR containing the genuine drift that has accumulated (UUPS/AccessControl members, removed Ownable functions). That PR will need entity-layer updates before merge and is expected to be breaking.Crowdsplit track
scripts/sync-crowdsplit.mjsbundles the OpenAPI spec from a crowdsplit checkout at a release tag, snapshots it topackages/payments/openapi/openapi.bundled.yaml, regenerates the internalsrc/generated/api.ts(openapi-typescript, exact-pinned), computes an endpoint-level diff plus an oasdiff changelog and breaking verdict, and writes a patch changeset. Output is deterministic; re-runs for the same tag are byte-identical no-ops. Runnable locally for dry runs.crowdsplit-sync.ymldrives it on thecrowdsplit-releaseddispatch and opens the PR (branchsync/crowdsplit-<tag>, labelsapi-sync/crowdsplit, plusbreaking-api-changewhen applicable). The PR body lists new and removed endpoints as a checklist for the follow-up service work.api-types-freshnessjob that regenerates the types from the committed snapshot and fails on any drift.dist/now contains the generated declarations.What stays manual
Merging sync PRs, writing service methods and tests for new endpoints, building entities for new contracts, escalating changesets for breaking releases, and all hand-written prose.
Setup required before the pipeline is live
CROWDSPLIT_READ_TOKEN(fine-grained PAT, Contents read on oak-network/crowdsplit) andSDK_BOT_TOKEN(fine-grained PAT on this repo, Contents + Pull requests read/write; needed so bot-created PRs trigger CI). (Note: Already created)Testing
forge build --astbundle and a real crowdsplit checkout at v2.1.1; second runs verified as no-ops. The freshness gate reproduces the committed generated types byte for byte.