Skip to content

Commit 30cd2eb

Browse files
committed
docs(sdk): one reference PR per SDK release, ready only once both packages are installable
Close the chain backend contract -> SDK -> docs on the receiving side. The sync workflow now takes `sdk-release` dispatches from the SDK's release-please (stage: candidate, the version PR's head) and publish (stage: released, the published commit) workflows, a weekly schedule that syncs the newest published release, and a manual run for any ref as a labelled preview draft. scripts/sdk-reference-release.mjs decides the branch and the publish state: one branch per Python/TypeScript version pair, so a retry or the candidate->released transition rewrites the same PR instead of failing on an existing branch; a no-op diff opens nothing and closes a PR main already carries. A released claim is downgraded to a draft unless futureagi==X is on PyPI and @future-agi/sdk@Y is on npm, checked here, so the docs never describe an SDK users cannot install. The default is the newest published release, not the SDK's dev branch. node --test covers the decision; actionlint passes on the workflow.
1 parent ab903e0 commit 30cd2eb

5 files changed

Lines changed: 332 additions & 34 deletions

File tree

Lines changed: 101 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,45 @@
1-
# Refreshes the platform SDK reference (src/pages/docs/sdk/reference) from the SDK
2-
# repository's generated pages and opens a PR against main. Run it by hand for a given SDK
3-
# ref, let the SDK repository dispatch it on a release, or rely on the weekly run.
1+
# The last link of the chain backend contract → futureagi-sdk → docs: syncs the
2+
# platform SDK reference (src/pages/docs/sdk/reference) from the generated pages
3+
# in a futureagi-sdk commit and opens or updates ONE pull request per SDK release.
4+
#
5+
# futureagi-sdk publish.yml → sdk-release {ref, stage: released} after PyPI and npm
6+
# futureagi-sdk release-please → sdk-release {ref, stage: candidate} when a version PR is prepared
7+
# schedule → newest published release (catches a missed dispatch)
8+
# workflow_dispatch → any ref; a preview draft unless `stage` says otherwise
9+
#
10+
# scripts/sdk-reference-release.mjs decides the branch (one per Python/TypeScript
11+
# version pair, so retries update the same PR) and whether the PR may be marked
12+
# ready: only when BOTH packages at those versions are installable from PyPI and
13+
# npm. Everything else is a draft. The docs site never documents an SDK that
14+
# users cannot install. Pages are never edited here; fix the generator in the SDK.
415
name: sdk-reference-sync
516

617
on:
18+
repository_dispatch:
19+
types: [sdk-release] # client_payload: ref (full commit SHA), stage (released|candidate), source (URL)
720
workflow_dispatch:
821
inputs:
922
sdk_ref:
10-
description: futureagi-sdk ref to sync from (branch, tag or SHA)
11-
default: dev
12-
repository_dispatch:
13-
types: [sdk-release] # client_payload.ref: the SDK ref to sync from
23+
description: futureagi-sdk commit, tag or branch (empty = newest published release)
24+
default: ''
25+
stage:
26+
description: 'released, candidate or preview (empty = preview for a ref, released otherwise)'
27+
default: ''
1428
schedule:
15-
- cron: '0 6 * * 1' # Mondays 06:00 UTC, from the SDK's dev branch
29+
- cron: '0 6 * * 1' # Mondays 06:00 UTC
1630

1731
permissions:
1832
contents: write
1933
pull-requests: write
2034

35+
concurrency:
36+
group: sdk-reference-sync
37+
cancel-in-progress: false
38+
2139
jobs:
2240
sync:
2341
runs-on: ubuntu-latest
24-
timeout-minutes: 10
42+
timeout-minutes: 15
2543
steps:
2644
# App token (not GITHUB_TOKEN): the org forbids Actions from creating PRs
2745
# with GITHUB_TOKEN, and App-minted tokens are exempt. Scoped to this repo.
@@ -34,44 +52,95 @@ jobs:
3452
with:
3553
ref: main
3654
token: ${{ steps.app-token.outputs.token }}
37-
- name: Resolve the SDK ref
38-
id: ref
55+
- uses: actions/setup-node@v4
56+
with:
57+
node-version: 20
58+
- name: Resolve the SDK release
59+
id: release
3960
env:
40-
INPUT_REF: ${{ inputs.sdk_ref }}
41-
DISPATCH_REF: ${{ github.event.client_payload.ref }}
42-
run: echo "ref=${INPUT_REF:-${DISPATCH_REF:-dev}}" >> "$GITHUB_OUTPUT"
43-
- name: Check out the generated reference from the SDK repository
61+
GH_TOKEN: ${{ github.token }}
62+
REF: ${{ inputs.sdk_ref || github.event.client_payload.ref }}
63+
STAGE: ${{ inputs.stage || github.event.client_payload.stage }}
64+
run: |
65+
set -eu
66+
if [ "$GITHUB_EVENT_NAME" = repository_dispatch ]; then
67+
# A sender names the exact commit it published; a branch name could move under us.
68+
[[ "$REF" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::sdk-release needs client_payload.ref as a full commit SHA, got '$REF'"; exit 1; }
69+
fi
70+
args=()
71+
[ -n "$REF" ] && args+=(--ref "$REF")
72+
[ -n "$STAGE" ] && args+=(--stage "$STAGE")
73+
node scripts/sdk-reference-release.mjs "${args[@]}" | tee -a "$GITHUB_OUTPUT"
74+
- name: Check out the generated reference from that SDK commit
4475
uses: actions/checkout@v4
4576
with:
4677
repository: future-agi/futureagi-sdk
47-
ref: ${{ steps.ref.outputs.ref }}
78+
ref: ${{ steps.release.outputs.sha }}
4879
path: .sdk
4980
sparse-checkout: docs/sdk-reference
5081
persist-credentials: false
51-
- uses: actions/setup-node@v4
52-
with:
53-
node-version: 20
5482
- name: Sync the pages and the sidebar group
5583
run: node scripts/sync-sdk-reference.mjs --from .sdk
5684
- name: Check nav and content links
5785
run: node scripts/audit-links.mjs
58-
- name: Open PR
86+
- name: Open, update or finish the pull request
5987
env:
6088
GH_TOKEN: ${{ steps.app-token.outputs.token }}
61-
SDK_REF: ${{ steps.ref.outputs.ref }}
89+
SHA: ${{ steps.release.outputs.sha }}
90+
REF: ${{ steps.release.outputs.ref }}
91+
PY: ${{ steps.release.outputs.python }}
92+
TS: ${{ steps.release.outputs.typescript }}
93+
BACKEND: ${{ steps.release.outputs.backend }}
94+
BRANCH: ${{ steps.release.outputs.branch }}
95+
STAGE: ${{ steps.release.outputs.stage }}
96+
PUBLISH: ${{ steps.release.outputs.publish }}
97+
SOURCE: ${{ github.event.client_payload.source || format('{0}/{1}/actions/runs/{2}', github.server_url, github.repository, github.run_id) }}
6298
run: |
6399
set -eu
100+
short=${SHA:0:12}
101+
sdk="https://github.com/future-agi/futureagi-sdk"
102+
number=$(gh pr list --head "$BRANCH" --base main --state open --json number --jq '.[0].number // empty')
64103
if git diff --quiet -- src/pages/docs/sdk/reference src/lib/sdk-reference.mjs; then
65-
echo "reference already current"; exit 0
104+
if [ -z "$number" ]; then
105+
echo "main already carries the reference of futureagi-sdk@$short; nothing to open"
106+
exit 0
107+
fi
108+
gh pr close "$number" --comment "main already carries the reference generated by futureagi-sdk@$short; nothing left to merge." \
109+
--delete-branch
110+
exit 0
66111
fi
67-
sha=$(git -C .sdk rev-parse --short HEAD)
68-
branch="chore/sdk-reference-${sha}"
69-
git config user.name "futureagi-release-bot"
70-
git config user.email "[email protected]"
71-
git switch -c "$branch"
112+
git config user.name "futureagi-release-bot[bot]"
113+
git config user.email "futureagi-release-bot[bot]@users.noreply.github.com"
114+
git switch -c "$BRANCH"
72115
git add src/pages/docs/sdk/reference src/lib/sdk-reference.mjs
73-
git commit -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@${sha}"
74-
git push origin "$branch"
75-
gh pr create --base main --head "$branch" \
76-
--title "docs(sdk): platform SDK reference from futureagi-sdk@${sha}" \
77-
--body "Generated pages from [future-agi/futureagi-sdk@${sha}](https://github.com/future-agi/futureagi-sdk/tree/${sha}/docs/sdk-reference) (ref \`${SDK_REF}\`), copied by \`scripts/sync-sdk-reference.mjs\`. Do not edit the pages here: fix the generator in the SDK repository and re-run the sync."
116+
git commit -q -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@$short" \
117+
-m "Python $PY, TypeScript $TS, backend contract $BACKEND ($STAGE)."
118+
# One branch per release: a retry or the candidate→released transition rewrites it.
119+
git push --force origin "$BRANCH"
120+
case "$STAGE" in
121+
released) title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS"
122+
stage_note="**Released.** \`futureagi==$PY\` is on [PyPI](https://pypi.org/project/futureagi/$PY/) and \`@future-agi/sdk@$TS\` on [npm](https://www.npmjs.com/package/@future-agi/sdk/v/$TS); this PR is ready for review." ;;
123+
candidate) title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS (candidate)"
124+
stage_note="**Candidate (draft).** The SDK release is prepared but \`futureagi==$PY\` and \`@future-agi/sdk@$TS\` are not both installable yet. The publish workflow re-dispatches once they are, and this PR is marked ready then. Do not merge before." ;;
125+
*) title="docs(sdk): platform SDK reference preview of futureagi-sdk@$short"
126+
stage_note="**Preview (draft).** Generated from \`$REF\`, which is not a published release. For looking only; the released PR for these versions is opened by the SDK publish workflow." ;;
127+
esac
128+
cat > "$RUNNER_TEMP/body.md" <<EOF
129+
Generated pages from [future-agi/futureagi-sdk@$short]($sdk/tree/$SHA/docs/sdk-reference): Python **$PY**, TypeScript **$TS**, backend contract **$BACKEND** (the SDK [sync PR]($sdk/pulls?q=is%3Apr+%22sync+with+backend+$BACKEND%22) names the backend release).
130+
131+
$stage_note
132+
133+
Copied by \`scripts/sync-sdk-reference.mjs\`; decided by \`scripts/sdk-reference-release.mjs\`. Do not edit the pages here: fix the generator in the SDK repository and re-run the sync. Source: $SOURCE
134+
EOF
135+
if [ -z "$number" ]; then
136+
draft=()
137+
[ "$PUBLISH" = draft ] && draft+=(--draft)
138+
gh pr create --base main --head "$BRANCH" --title "$title" --body-file "$RUNNER_TEMP/body.md" "${draft[@]}"
139+
number=$(gh pr list --head "$BRANCH" --base main --state open --json number --jq '.[0].number')
140+
else
141+
gh pr edit "$number" --title "$title" --body-file "$RUNNER_TEMP/body.md" >/dev/null
142+
fi
143+
if [ "$PUBLISH" = ready ]; then
144+
gh pr ready "$number" 2>/dev/null || true
145+
fi
146+
echo "future-agi/docs#$number ($STAGE, $PUBLISH)"

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
"astro": "astro",
1212
"new-doc": "node scripts/new-doc.mjs",
1313
"audit-links": "node scripts/audit-links.mjs",
14-
"test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs",
14+
"test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/sdk-reference-release.test.mjs",
1515
"test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs",
1616
"check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs"
1717
},

‎scripts/sdk-reference-release.mjs‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
// @ts-check
2+
/**
3+
* Decide which futureagi-sdk revision the reference should be synced from, and
4+
* whether the resulting docs PR may be published as stable or must stay a draft.
5+
*
6+
* node scripts/sdk-reference-release.mjs [--ref <sha|tag|branch>] [--stage released|candidate|preview] [--json]
7+
*
8+
* Without --ref it picks the newest published SDK release: the commit of the
9+
* newest `python-v*` tag. The result (printed as `key=value` lines, or JSON with
10+
* --json) carries the full commit SHA, the Python/TypeScript versions from the
11+
* SDK's release manifest at that commit, the backend release the contract was
12+
* synced from, and `branch`, the docs branch for this release: one branch (so one
13+
* PR) per SDK version pair, however many times the sync runs.
14+
*
15+
* `stage` is what the caller claims; `publish` is what the registries confirm.
16+
* A `released` claim is downgraded to `candidate` unless BOTH packages at those
17+
* versions are installable from PyPI and npm, so a docs PR never leaves draft
18+
* for an SDK users cannot install yet. `preview` (any ref, usually dev) is
19+
* always a draft and gets its own branch keyed by commit.
20+
*
21+
* Reads only public endpoints (api.github.com, pypi.org, registry.npmjs.org);
22+
* GH_TOKEN or GITHUB_TOKEN is used for GitHub when present to avoid rate limits.
23+
* .github/workflows/sdk-reference-sync.yml runs it; `node --test scripts/` covers it.
24+
*/
25+
import process from 'node:process';
26+
27+
export const SDK_REPO = 'future-agi/futureagi-sdk';
28+
const STAGES = new Set(['released', 'candidate', 'preview']);
29+
30+
/** @param {string} url @param {RequestInit} [init] */
31+
async function fetchJson(url, init) {
32+
const response = await fetch(url, init);
33+
if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`);
34+
return response.json();
35+
}
36+
37+
/** @param {string} path */
38+
async function github(path) {
39+
const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
40+
/** @type {Record<string, string>} */
41+
const headers = { accept: 'application/vnd.github+json', 'user-agent': 'future-agi-docs-sdk-reference' };
42+
if (token) headers.authorization = `Bearer ${token}`;
43+
return fetchJson(`https://api.github.com/repos/${SDK_REPO}/${path}`, { headers });
44+
}
45+
46+
/** The newest python-v* tag's name (by semantic version, not by push order). */
47+
export function newestPythonTag(/** @type {{ref: string}[]} */ refs) {
48+
const versions = refs
49+
.map((ref) => ref.ref.replace('refs/tags/', ''))
50+
.map((tag) => ({ tag, match: /^python-v(\d+)\.(\d+)\.(\d+)$/.exec(tag) }))
51+
.filter((entry) => entry.match)
52+
.map((entry) => ({ tag: entry.tag, version: entry.match.slice(1, 4).map(Number) }))
53+
.sort((a, b) => a.version[0] - b.version[0] || a.version[1] - b.version[1] || a.version[2] - b.version[2]);
54+
if (!versions.length) throw new Error(`${SDK_REPO} has no python-v* release tag yet`);
55+
return versions[versions.length - 1].tag;
56+
}
57+
58+
/** @param {string} ref a tag, branch or commit; returns the full commit SHA. */
59+
async function resolveSha(ref) {
60+
const commit = await github(`commits/${encodeURIComponent(ref)}`);
61+
if (!/^[0-9a-f]{40}$/.test(commit.sha)) throw new Error(`cannot resolve ${ref} to a commit`);
62+
return commit.sha;
63+
}
64+
65+
/** @param {string} path @param {string} sha */
66+
async function fileAt(path, sha) {
67+
const file = await github(`contents/${path}?ref=${sha}`);
68+
return Buffer.from(file.content, 'base64').toString('utf-8');
69+
}
70+
71+
/** @param {string} version */
72+
export async function onPyPI(version) {
73+
const response = await fetch(`https://pypi.org/pypi/futureagi/${version}/json`);
74+
return response.status === 200;
75+
}
76+
77+
/** @param {string} version */
78+
export async function onNpm(version) {
79+
const response = await fetch(`https://registry.npmjs.org/@future-agi%2fsdk/${version}`);
80+
return response.status === 200;
81+
}
82+
83+
/**
84+
* Pure part: branch and publish decision from the facts.
85+
* @param {{stage: string, sha: string, python: string, typescript: string, installable: boolean}} facts
86+
*/
87+
export function decide({ stage, sha, python, typescript, installable }) {
88+
if (!STAGES.has(stage)) throw new Error(`stage must be one of ${[...STAGES].join(', ')}, not ${stage}`);
89+
if (stage === 'preview') {
90+
return { branch: `sdk-reference/preview-${sha.slice(0, 12)}`, publish: 'draft', stage };
91+
}
92+
const branch = `sdk-reference/python-v${python}-typescript-v${typescript}`;
93+
if (stage === 'released' && installable) return { branch, publish: 'ready', stage };
94+
return { branch, publish: 'draft', stage: 'candidate' };
95+
}
96+
97+
/**
98+
* @param {{ref?: string, stage?: string}} options
99+
* @param {{resolveSha?: typeof resolveSha, fileAt?: typeof fileAt, tags?: () => Promise<{ref: string}[]>, onPyPI?: typeof onPyPI, onNpm?: typeof onNpm}} [io]
100+
*/
101+
export async function resolve(options, io = {}) {
102+
const get = {
103+
resolveSha: io.resolveSha ?? resolveSha,
104+
fileAt: io.fileAt ?? fileAt,
105+
tags: io.tags ?? (() => github('git/matching-refs/tags/python-v')),
106+
onPyPI: io.onPyPI ?? onPyPI,
107+
onNpm: io.onNpm ?? onNpm,
108+
};
109+
let ref = options.ref?.trim() || '';
110+
let stage = options.stage?.trim() || (ref ? 'preview' : 'released');
111+
if (!ref) {
112+
ref = newestPythonTag(await get.tags());
113+
stage = options.stage?.trim() || 'released';
114+
}
115+
const sha = await get.resolveSha(ref);
116+
const manifest = JSON.parse(await get.fileAt('.release-please-manifest.json', sha));
117+
const python = manifest['python'];
118+
const typescript = manifest['typescript/futureagi'];
119+
if (!python || !typescript) throw new Error(`release manifest at ${sha} lacks the python or typescript/futureagi version`);
120+
const backend = (await get.fileAt('sdkgen/contracts/BACKEND_VERSION', sha)).trim();
121+
const installable = stage === 'released' ? (await get.onPyPI(python)) && (await get.onNpm(typescript)) : false;
122+
const decision = decide({ stage, sha, python, typescript, installable });
123+
return { ref, sha, python, typescript, backend, installable, ...decision };
124+
}
125+
126+
function parseArgs(argv) {
127+
/** @type {{ref?: string, stage?: string, json?: boolean}} */
128+
const options = {};
129+
for (let i = 0; i < argv.length; i++) {
130+
if (argv[i] === '--ref') options.ref = argv[++i];
131+
else if (argv[i] === '--stage') options.stage = argv[++i];
132+
else if (argv[i] === '--json') options.json = true;
133+
else throw new Error(`unknown argument ${argv[i]}`);
134+
}
135+
return options;
136+
}
137+
138+
if (process.argv[1] && import.meta.url === new URL(process.argv[1], 'file://').href) {
139+
const options = parseArgs(process.argv.slice(2));
140+
resolve(options)
141+
.then((result) => {
142+
if (options.json) {
143+
console.log(JSON.stringify(result, null, 2));
144+
} else {
145+
for (const [key, value] of Object.entries(result)) console.log(`${key}=${value}`);
146+
}
147+
})
148+
.catch((error) => {
149+
console.error(error.message);
150+
process.exit(1);
151+
});
152+
}

0 commit comments

Comments
 (0)