Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions .github/workflows/sdk-reference-sync.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# The last link of the chain backend contract → futureagi-sdk → docs: syncs the
# platform SDK reference (src/pages/docs/sdk/reference) from the generated pages
# in a futureagi-sdk commit and opens or updates ONE pull request per SDK release.
#
# futureagi-sdk publish.yml → sdk-release {ref, stage: released} after PyPI and npm
# futureagi-sdk release-please → sdk-release {ref, stage: candidate} when a version PR is prepared
# schedule → newest published release (catches a missed dispatch)
# workflow_dispatch → any ref; a preview draft unless `stage` says otherwise
#
# scripts/sdk-reference-release.mjs decides the branch (one per Python/TypeScript
# version pair, so retries update the same PR) and whether the PR may be marked
# ready: only when the source commit matches a component release tag and BOTH
# manifest versions are installable from PyPI and npm. Everything else is a draft.
# The docs site never documents an SDK that
# users cannot install. Pages are never edited here; fix the generator in the SDK.
name: sdk-reference-sync

on:
repository_dispatch:
types: [sdk-release] # client_payload: ref (full commit SHA), stage (released|candidate), source (URL)
workflow_dispatch:
inputs:
sdk_ref:
description: futureagi-sdk commit, tag or branch (empty = newest published release)
default: ''
stage:
description: 'released, candidate or preview (empty = preview for a ref, released otherwise)'
default: ''
schedule:
- cron: '0 6 * * 1' # Mondays 06:00 UTC

permissions:
contents: write
pull-requests: write

concurrency:
group: sdk-reference-sync
cancel-in-progress: false

jobs:
sync:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
# App token (not GITHUB_TOKEN): the org forbids Actions from creating PRs
# with GITHUB_TOKEN, and App-minted tokens are exempt. Scoped to this repo.
- uses: actions/create-github-app-token@v2
id: app-token
with:
app-id: ${{ secrets.RELEASE_BOT_APP_ID }}
private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
- uses: actions/checkout@v4
with:
ref: main
token: ${{ steps.app-token.outputs.token }}
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Resolve the SDK release
id: release
env:
GH_TOKEN: ${{ github.token }}
REF: ${{ inputs.sdk_ref || github.event.client_payload.ref }}
STAGE: ${{ inputs.stage || github.event.client_payload.stage }}
run: |
set -eu
if [ "$GITHUB_EVENT_NAME" = repository_dispatch ]; then
# A sender names the exact commit it published; a branch name could move under us.
[[ "$REF" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::sdk-release needs client_payload.ref as a full commit SHA, got '$REF'"; exit 1; }
fi
args=()
[ -n "$REF" ] && args+=(--ref "$REF")
[ -n "$STAGE" ] && args+=(--stage "$STAGE")
node scripts/sdk-reference-release.mjs "${args[@]}" | tee -a "$GITHUB_OUTPUT"
- name: Check out the generated reference from that SDK commit
uses: actions/checkout@v4
with:
repository: future-agi/futureagi-sdk
ref: ${{ steps.release.outputs.sha }}
path: .sdk
sparse-checkout: |
docs/sdk-reference
sdkgen
python/fi/platform
typescript/futureagi/src/platform
persist-credentials: false
# The initial published release predates the docs generator. Render ONLY
# that release's contract/catalog with the reviewed emitter pinned below.
# Never substitute dev's contract, catalog or generated pages.
- name: Check out the pinned bootstrap emitter
if: steps.release.outputs.sha == 'e61149de72c9907abd0921371126e4d40eb3e04a'
uses: actions/checkout@v4
with:
repository: future-agi/futureagi-sdk
ref: 3269d584fc668f959d8c125cf9acb33d3c36d1fb
path: .sdk-renderer
sparse-checkout: sdkgen/generator
persist-credentials: false
- uses: actions/setup-python@v5
if: steps.release.outputs.sha == 'e61149de72c9907abd0921371126e4d40eb3e04a'
with:
python-version: '3.12'
- name: Render the initial published release reference
if: steps.release.outputs.sha == 'e61149de72c9907abd0921371126e4d40eb3e04a'
run: |
python -m pip install PyYAML==6.0.2
python -I scripts/bootstrap-sdk-reference.py --sdk .sdk --renderer .sdk-renderer
- name: Sync the pages and the sidebar group
run: node scripts/sync-sdk-reference.mjs --from .sdk
- name: Check nav and content links
run: node scripts/audit-links.mjs
- name: Open, update or finish the pull request
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
SHA: ${{ steps.release.outputs.sha }}
REF: ${{ steps.release.outputs.ref }}
PY: ${{ steps.release.outputs.python }}
TS: ${{ steps.release.outputs.typescript }}
BACKEND: ${{ steps.release.outputs.backend }}
BRANCH: ${{ steps.release.outputs.branch }}
STAGE: ${{ steps.release.outputs.stage }}
PUBLISH: ${{ steps.release.outputs.publish }}
SOURCE: ${{ github.event.client_payload.source || format('{0}/{1}/actions/runs/{2}', github.server_url, github.repository, github.run_id) }}
# scripts/sdk-reference-pr.sh holds the state rules (a stale candidate event never
# downgrades or rewrites a released PR; a ready decision is verified, not assumed)
# and scripts/sdk-reference-pr.test.mjs runs it against a fake gh/git.
run: bash scripts/sdk-reference-pr.sh
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
"astro": "astro",
"new-doc": "node scripts/new-doc.mjs",
"audit-links": "node scripts/audit-links.mjs",
"test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/langfuse-import.test.mjs scripts/n8n-page.test.mjs scripts/openlit-endpoint.test.mjs scripts/chromadb-java.test.mjs scripts/openllmetry-content.test.mjs scripts/langflow-page.test.mjs",
"test:integrations:browser": "node scripts/browser-network.browser.cjs && node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs && node scripts/auto.browser.mjs",
"test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/langfuse-import.test.mjs scripts/n8n-page.test.mjs scripts/openlit-endpoint.test.mjs scripts/chromadb-java.test.mjs scripts/openllmetry-content.test.mjs scripts/langflow-page.test.mjs scripts/sdk-reference-release.test.mjs scripts/sdk-reference-pr.test.mjs",
"test:integrations:browser": "node scripts/browser-network.browser.cjs && node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs && node scripts/auto.browser.mjs && node scripts/sdk-reference-mobile.cjs",
"check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs"
},
"dependencies": {
Expand Down
59 changes: 59 additions & 0 deletions scripts/SDK_REFERENCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Released SDK reference

The stable reference must describe packages that readers can install. The
backend contract/catalog in SDK `dev` is not a substitute for a released SDK,
even when its manifest still contains the same version strings.

## Normal synchronization

`sdk-reference-release.mjs` selects the latest release across both package tag
streams. A `released` request becomes ready only when the selected SDK commit
matches a tag for one of the manifest's package versions and **both** versions
exist in their registries. An untagged commit with published version strings
stays a candidate draft. Independent Python-only and TypeScript-only releases
remain supported only when the other package's Git tree is identical to its own
release tag; unversioned source changes cannot hide behind an installable version.

`sync-sdk-reference.mjs --from <sdk checkout>` copies the SDK-generated pages
and navigation. It also records the immutable SDK commit, package versions and
backend pin in `src/lib/sdk-reference-source.json`. That provenance file travels
in the same update as the pages; it is not edited by hand.

## First-release bootstrap

Python 0.7.0 and TypeScript 0.2.0 were published from
`e61149de72c9907abd0921371126e4d40eb3e04a`, before the docs emitter existed.
That release contains **162** platform methods. The later `dev` reference added
methods that these packages do not contain, so copying it would be incorrect.

For this one historical commit, `bootstrap-sdk-reference.py` runs the reviewed
emitter at `3269d584fc668f959d8c125cf9acb33d3c36d1fb` with **only the released
commit's contract and catalog**. Before rendering, it checks both immutable
checkout heads and verifies that these inputs regenerate the exact released
Python and TypeScript operation files. Neither API inputs nor generated clients
are copied from the emitter's newer checkout. Other releases must carry their
own generated reference; they do not silently fall back to `dev`.

The sync workflow contains this same pinned bootstrap, so scheduled recovery
also works before the next SDK release. It can be reproduced in a disposable
cloud environment:

```sh
python -m pip install PyYAML==6.0.2
python -I scripts/bootstrap-sdk-reference.py --sdk /path/to/released-sdk --renderer /path/to/pinned-emitter
node scripts/sync-sdk-reference.mjs --from /path/to/released-sdk
```

## Verification

- Run the resolver and PR-lifecycle tests, including an untagged commit that
retains published version strings, an independent package release, and failed
GitHub lookups.
- Check every Python example against the **installed published wheel**, and
compile every TypeScript example against the **installed published npm package**.
- Build the site, audit its links and exercise all reference pages at phone width.
- Run generation twice and compare output to catch accidental input drift.

Merging the docs receiver does not deploy the sender. The SDK's docs-dispatch
changes still need their own reviewed promotion to SDK `main`; package
publication is separate from this docs change.
2 changes: 2 additions & 0 deletions scripts/audit-links.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
import { integrationNavigation } from '../src/lib/integrations.mjs';
import { sdkReferenceNavigation } from '../src/lib/sdk-reference.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(__dirname, '..');
Expand Down Expand Up @@ -67,6 +68,7 @@ function addCatalogLinks(items) {
}
}
addCatalogLinks(integrationNavigation);
addCatalogLinks(sdkReferenceNavigation.items);

// ── 3. Extract all internal links from MDX files ──────────────
function findMdxFiles(dir) {
Expand Down
68 changes: 68 additions & 0 deletions scripts/bootstrap-sdk-reference.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
"""Render the first published SDK's reference without importing the dev API surface.

The 0.7.0/0.2.0 release predates the docs emitter. Only this immutable release
uses the bridge; later SDK releases must carry their own generated reference.
The emitter is also pinned. Its contract/catalog inputs ALWAYS come from the
published checkout, never the emitter checkout. Run in CI/cloud, not locally:

python -I scripts/bootstrap-sdk-reference.py --sdk .sdk --renderer .sdk-renderer
"""
from __future__ import annotations

import argparse
import json
from pathlib import Path
import subprocess
import sys

RELEASE = "e61149de72c9907abd0921371126e4d40eb3e04a"
RENDERER = "3269d584fc668f959d8c125cf9acb33d3c36d1fb"


def head(root: Path) -> str:
return subprocess.check_output(["git", "-C", str(root), "rev-parse", "HEAD"], text=True).strip()


def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--sdk", required=True, type=Path)
parser.add_argument("--renderer", required=True, type=Path)
args = parser.parse_args()
sdk, renderer = args.sdk.resolve(), args.renderer.resolve()
if head(sdk) != RELEASE or head(renderer) != RENDERER:
raise ValueError("bootstrap requires the pinned published SDK and reviewed emitter commits")
for root in (sdk, renderer):
# Generated output may already exist for a deterministic rerun, but input
# files must not be edited after checking out the verified commits.
changed = subprocess.check_output(
["git", "-C", str(root), "status", "--porcelain", "--untracked-files=all", "--", "sdkgen", "python/fi/platform", "typescript/futureagi/src/platform"],
text=True,
)
if changed.strip():
raise ValueError("bootstrap inputs differ from their pinned commits")
sys.path.insert(0, str(renderer))
import yaml
from sdkgen.generator import docs, python, typescript
from sdkgen.generator.catalog import load

spec = json.loads((sdk / "sdkgen/contracts/swagger.json").read_text())
catalog = yaml.safe_load((sdk / "sdkgen/catalog/operations.yaml").read_text())
ops = load(spec, catalog)
# The emitter must see precisely the released operation definitions in both
# languages, including parameters; merely counting method names is not enough.
expected = {
"python/fi/platform/_operations.py": python.emit_operations(ops),
"typescript/futureagi/src/platform/_operations.ts": typescript.emit_operations(ops),
}
for name, text in expected.items():
if (sdk / name).read_text() != text:
raise ValueError(f"renderer inputs do not reproduce the released {name}")
out = sdk / "docs/sdk-reference"
out.mkdir(parents=True, exist_ok=True)
for name, text in docs.emit_pages(spec, ops).items():
(out / name).write_text(text)
print(f"Rendered published SDK {RELEASE} using emitter {RENDERER}; {len(ops)} operations")


if __name__ == "__main__":
main()
59 changes: 59 additions & 0 deletions scripts/sdk-reference-mobile.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
// Phone-width regression for the generated platform SDK reference: every page in the
// sidebar group must fit a 390 px viewport with no horizontal page scroll, and every
// reference table must sit in a bounded scroller (.sdk-ref-table) so wide identifiers
// scroll inside the table instead of widening the document. Runs against the preview
// on 127.0.0.1:4321 (npm run build && npm run preview), like integrations.browser.cjs.
const { chromium } = require('playwright');
const assert = require('node:assert/strict');
const path = require('node:path');

const BASE = 'http://127.0.0.1:4321';
const WIDTH = 390;

async function routes() {
const { sdkReferenceNavigation } = await import(path.join(__dirname, '..', 'src', 'lib', 'sdk-reference.mjs'));
const out = [];
const walk = (items) => {
for (const item of items) {
if (item.href) out.push(item.href);
if (item.items) walk(item.items);
}
};
walk(sdkReferenceNavigation.items);
return out;
}

(async () => {
let ready = false;
for (let i = 0; i < 30 && !ready; i++) {
try { if ((await fetch(BASE + '/docs/sdk/reference')).ok) ready = true; else await new Promise((r) => setTimeout(r, 1000)); } catch { await new Promise((r) => setTimeout(r, 1000)); }
}
assert.ok(ready, 'Start the docs preview on 127.0.0.1:4321 before running browser checks');
const hrefs = await routes();
assert.ok(hrefs.length >= 30, `expected the full reference in the sidebar, found ${hrefs.length} routes`);
const browser = await chromium.launch({ headless: true });
const ctx = await browser.newContext({ viewport: { width: WIDTH, height: 844 }, colorScheme: 'dark' });
const page = await ctx.newPage();
const failures = [];
for (const href of hrefs) {
await page.goto(BASE + href + '/', { waitUntil: 'networkidle' });
const m = await page.evaluate(() => ({
scrollWidth: document.documentElement.scrollWidth,
clientWidth: document.documentElement.clientWidth,
tables: document.querySelectorAll('.docs-content table').length,
unwrapped: [...document.querySelectorAll('.docs-content table')].filter((t) => !t.closest('.sdk-ref-table')).length,
offscreen: [...document.querySelectorAll('.docs-content h2, .docs-content h3, .docs-content td, .docs-content pre')]
.filter((el) => el.getBoundingClientRect().left < 0).length,
}));
if (m.scrollWidth > m.clientWidth) failures.push(`${href}: document scrolls to ${m.scrollWidth}px at a ${m.clientWidth}px viewport`);
if (m.unwrapped) failures.push(`${href}: ${m.unwrapped} table(s) not inside .sdk-ref-table`);
if (m.offscreen) failures.push(`${href}: ${m.offscreen} element(s) start left of the viewport (clipped content)`);
console.log(`${href}: ${m.scrollWidth}px wide, ${m.tables} table(s)`);
}
await browser.close();
assert.deepEqual(failures, [], failures.join('\n'));
console.log(`sdk reference mobile: ${hrefs.length} pages fit ${WIDTH}px with bounded tables`);
})().catch((error) => {
console.error(error.message || error);
process.exit(1);
});
Loading
Loading