|
| 1 | +// @ts-check |
| 2 | +/** |
| 3 | + * Copy the generated platform SDK reference out of a futureagi-sdk checkout. |
| 4 | + * |
| 5 | + * node scripts/sync-sdk-reference.mjs --from ../futureagi-sdk |
| 6 | + * |
| 7 | + * The SDK repository generates `docs/sdk-reference/` (one MDX page per resource, an |
| 8 | + * overview, and `navigation.json`) from its API contract with `python sdkgen/generate.py`. |
| 9 | + * This script replaces `src/pages/docs/sdk/reference/` with those pages and rewrites |
| 10 | + * `src/lib/sdk-reference.mjs`, the sidebar group `navigation.ts` imports. Never edit the |
| 11 | + * copied pages by hand: fix the generator in the SDK repository and sync again. |
| 12 | + * `.github/workflows/sdk-reference-sync.yml` runs this and opens a PR. |
| 13 | + */ |
| 14 | +import fs from 'node:fs'; |
| 15 | +import path from 'node:path'; |
| 16 | +import { fileURLToPath } from 'node:url'; |
| 17 | + |
| 18 | +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); |
| 19 | +const PAGES_DIR = path.join(ROOT, 'src/pages/docs/sdk/reference'); |
| 20 | +const NAV_FILE = path.join(ROOT, 'src/lib/sdk-reference.mjs'); |
| 21 | + |
| 22 | +const args = process.argv.slice(2); |
| 23 | +const fromIndex = args.indexOf('--from'); |
| 24 | +if (fromIndex === -1 || !args[fromIndex + 1]) { |
| 25 | + console.error('usage: node scripts/sync-sdk-reference.mjs --from <path to a futureagi-sdk checkout>'); |
| 26 | + process.exit(2); |
| 27 | +} |
| 28 | +const source = path.resolve(args[fromIndex + 1], 'docs/sdk-reference'); |
| 29 | +const navSource = path.join(source, 'navigation.json'); |
| 30 | +if (!fs.existsSync(path.join(source, 'index.mdx')) || !fs.existsSync(navSource)) { |
| 31 | + console.error(`${source} does not hold a generated reference (index.mdx + navigation.json); run python sdkgen/generate.py in the SDK checkout first`); |
| 32 | + process.exit(1); |
| 33 | +} |
| 34 | + |
| 35 | +/** @type {{group: string, icon?: string, items: {title: string, href?: string, items?: {title: string, href: string}[]}[]}} */ |
| 36 | +const nav = JSON.parse(fs.readFileSync(navSource, 'utf-8')); |
| 37 | +const pages = fs.readdirSync(source).filter((name) => name.endsWith('.mdx')).sort(); |
| 38 | + |
| 39 | +// Every nav item must have a page and every page a nav item, or the sidebar and the site drift. |
| 40 | +/** @param {{href?: string, items?: any[]}[]} items */ |
| 41 | +function* walk(items) { |
| 42 | + for (const item of items) { |
| 43 | + if (item.href) yield item.href; |
| 44 | + if (item.items) yield* walk(item.items); |
| 45 | + } |
| 46 | +} |
| 47 | +const hrefs = new Set(walk(nav.items)); |
| 48 | +for (const page of pages) { |
| 49 | + const href = page === 'index.mdx' ? '/docs/sdk/reference' : `/docs/sdk/reference/${page.replace(/\.mdx$/, '')}`; |
| 50 | + if (!hrefs.has(href)) { |
| 51 | + console.error(`${page} is not in navigation.json`); |
| 52 | + process.exit(1); |
| 53 | + } |
| 54 | + hrefs.delete(href); |
| 55 | +} |
| 56 | +if (hrefs.size) { |
| 57 | + console.error(`navigation.json lists pages that do not exist: ${[...hrefs].join(', ')}`); |
| 58 | + process.exit(1); |
| 59 | +} |
| 60 | + |
| 61 | +fs.mkdirSync(PAGES_DIR, { recursive: true }); |
| 62 | +let removed = 0; |
| 63 | +for (const name of fs.readdirSync(PAGES_DIR)) { |
| 64 | + if (name.endsWith('.mdx') && !pages.includes(name)) { |
| 65 | + fs.unlinkSync(path.join(PAGES_DIR, name)); |
| 66 | + removed++; |
| 67 | + } |
| 68 | +} |
| 69 | +for (const page of pages) { |
| 70 | + fs.copyFileSync(path.join(source, page), path.join(PAGES_DIR, page)); |
| 71 | +} |
| 72 | + |
| 73 | +const navModule = `// @ts-check |
| 74 | +/** |
| 75 | + * Sidebar group for the platform SDK reference. Generated by |
| 76 | + * scripts/sync-sdk-reference.mjs from the SDK repository's docs/sdk-reference/navigation.json; |
| 77 | + * do not edit. navigation.ts places it in the SDK tab and scripts/audit-links.mjs audits it. |
| 78 | + * |
| 79 | + * @type {{group: string, icon?: string, items: ReadonlyArray<{title: string, href?: string, items?: ReadonlyArray<{title: string, href: string}>}>}} |
| 80 | + */ |
| 81 | +export const sdkReferenceNavigation = ${JSON.stringify(nav, null, 2)}; |
| 82 | +`; |
| 83 | +fs.writeFileSync(NAV_FILE, navModule); |
| 84 | + |
| 85 | +console.log(`sdk reference: ${pages.length} pages copied, ${removed} stale removed, ${[...walk(nav.items)].length} nav links`); |
0 commit comments