|
| 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