docs: add docs:generate root script and update api doc generator

Author: richiemcilroy

apps/docs/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "next dev --turbopack -p 3002",
-    "build": "next build --turbopack",
+    "build": "bun run generate:api && next build --turbopack",
     "start": "next start",
     "typecheck": "fumadocs-mdx && tsc --noEmit",
     "generate:api": "bun run scripts/generate-api-docs.ts"

apps/docs/scripts/generate-api-docs.ts

@@ -1,17 +1,27 @@
 import { generateFiles } from 'fumadocs-openapi';
 import { spec } from '../../api/src/openapi.js';
+import { generateLlmsDocuments } from '../../api/src/llms.js';
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-const outDir = join(import.meta.dirname, '..', 'content', 'docs', 'api-reference');
+const appRoot = join(import.meta.dirname, '..');
+const outDir = join(appRoot, 'content', 'docs', 'api-reference');
+const publicDir = join(appRoot, 'public');
+const generatedSpecPath = join(outDir, 'openapi.json');
 
 mkdirSync(outDir, { recursive: true });
+mkdirSync(publicDir, { recursive: true });
 
-const specPath = join(outDir, 'openapi.json');
-writeFileSync(specPath, JSON.stringify(spec, null, 2));
+writeFileSync(generatedSpecPath, JSON.stringify(spec, null, 2));
+
+for (const [filename, content] of Object.entries(generateLlmsDocuments())) {
+  writeFileSync(join(publicDir, filename), content);
+}
+
+process.chdir(appRoot);
 
 void generateFiles({
-  input: [specPath],
-  output: outDir,
+  input: ['content/docs/api-reference/openapi.json'],
+  output: 'content/docs/api-reference',
   groupBy: 'tag',
 });

apps/docs/src/lib/source.test.ts

@@ -1,8 +1,10 @@
 import { describe, test, expect } from 'bun:test'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 const contentDir = join(import.meta.dirname, '../../content/docs')
+const apiReferenceDir = join(contentDir, 'api-reference')
+const repoRoot = join(import.meta.dirname, '../../../..')
 
 describe('docs content', () => {
   test('content directory exists', () => {
@@ -90,4 +92,35 @@ describe('openapi spec generation', () => {
     expect(tagNames).toContain('Artifacts')
     expect(tagNames).toContain('Replay')
   })
+
+  test('openapi.json artifact is generated from the live openapi spec', async () => {
+    const { spec } = await import('../../../api/src/openapi.js')
+    const specPath = join(apiReferenceDir, 'openapi.json')
+
+    expect(existsSync(specPath)).toBe(true)
+    expect(JSON.parse(readFileSync(specPath, 'utf8'))).toEqual(spec)
+  })
+
+  test('generated api pages live under the canonical docs tree without absolute path leakage', () => {
+    const generatedPagePath = join(apiReferenceDir, 'health/get-health.mdx')
+    const leakedOutputRoot = join(import.meta.dirname, '../../Users')
+
+    expect(existsSync(generatedPagePath)).toBe(true)
+    expect(existsSync(leakedOutputRoot)).toBe(false)
+
+    const content = readFileSync(generatedPagePath, 'utf8')
+    expect(content).toContain('<APIPage document={"content/docs/api-reference/openapi.json"}')
+    expect(content.includes(repoRoot)).toBe(false)
+  })
+
+  test('llms artifacts are generated from the live openapi spec', async () => {
+    const { generateLlmsDocuments } = await import('../../../api/src/llms.js')
+    const publicDir = join(import.meta.dirname, '../../public')
+
+    for (const [filename, content] of Object.entries(generateLlmsDocuments())) {
+      const filePath = join(publicDir, filename)
+      expect(existsSync(filePath)).toBe(true)
+      expect(readFileSync(filePath, 'utf8')).toBe(content)
+    }
+  })
 })

package.json

@@ -13,6 +13,7 @@
     "test": "turbo test",
     "test:e2e": "turbo test:e2e",
     "dev": "turbo run dev",
+    "docs:generate": "bun run --filter @sandchest/docs generate:api",
     "db:up": "bun run scripts/db-up.ts",
     "db:down": "docker compose down",
     "db:reset": "docker compose down -v && bun run db:up",