@stainless-api/docs 0.1.0-beta.8 → 0.1.0-beta.80

package/plugin/index.ts

@@ -1,9 +1,10 @@
 import react from '@astrojs/react';
 import type { StarlightPlugin } from '@astrojs/starlight/types';
-import type { AstroIntegration } from 'astro';
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
+import type { BundledTheme } from 'shiki';
 import { config } from 'dotenv';
 import getPort from 'get-port';
-import { startDevServer } from './cms/server';
+import { startDevServer, type SpecResp } from './cms/server';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import {
   getAPIReferencePlaceholderItemFromSidebarConfig,
@@ -21,13 +22,21 @@ import {
   type SpecRetrieverConfig,
 } from './loadPluginConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
+import type * as StlStarlightVirtualModule from 'virtual:stl-starlight-virtual-module';
 import path from 'path';
 import fs from 'fs';
+import { getSharedLogger } from '../shared/getSharedLogger';
+import { resolveSrcFile } from '../resolveSrcFile';
+import { mkdir, writeFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import prebundleWorkers from 'vite-plugin-prebundle-workers';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
 
-config();
+config({
+  quiet: true,
+});
 
 let sidebarIdCounter = 0;
 
@@ -108,20 +117,25 @@ function tmpGetCMSServerConfig(specRetrieverConfig: SpecRetrieverConfig) {
 
 async function stlStarlightAstroIntegration(
   pluginConfig: NormalizedStainlessStarlightConfig,
+  stlStarlightPluginLogger: AstroIntegrationLogger,
 ): Promise<AstroIntegration> {
   const virtualId = `virtual:stl-starlight-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolvedId = `\0${virtualId}`;
+  let playgroundsBase: string | undefined;
+  let buildPlaygrounds;
+  let astroBase = '/';
 
   const CMS_PORT = await getPort();
 
   const { apiKey, version, devPaths } = tmpGetCMSServerConfig(pluginConfig.specRetrieverConfig);
 
-  const cmsServer = await startDevServer({
+  const cmsServer = startDevServer({
     port: CMS_PORT,
-    apiKey,
+    apiKey: apiKey.value,
     version,
     devPaths,
+    logger: stlStarlightPluginLogger,
     getGeneratedSidebarConfig: (id: number) => {
       const config = sidebarConfigs.get(id);
       if (!config) {
@@ -131,50 +145,99 @@ async function stlStarlightAstroIntegration(
     },
   });
 
+  let building: Promise<void> | undefined;
+  let reportError: ((message: string) => void) | null = null;
+  let collectedErrors: string[] | null = null;
+
+  function startPlaygroundsBuild(playgroundsCachePath: string) {
+    if (!pluginConfig.experimentalPlaygrounds) return;
+    if (building) return building;
+    return (building = (async () => {
+      const { data: spec, auth } = (await (
+        await fetch(`http://localhost:${CMS_PORT}/retrieve_spec`, {
+          method: 'POST',
+          body: JSON.stringify({}),
+        })
+      ).json()) as SpecResp;
+      if (!spec || !auth) throw new Error('expected spec');
+
+      const langs = (spec.docs?.languages ?? ['http'])
+        .filter((lang) => lang !== 'terraform')
+        .filter((lang) => !pluginConfig.excludeLanguages?.includes(lang));
+
+      await buildPlaygrounds!({
+        spec,
+        langs,
+        auth,
+        playPath: playgroundsCachePath,
+        reportError(message: string) {
+          (reportError ?? console.error)(message);
+        },
+      });
+    })());
+  }
+
   return {
     name: 'stl-starlight-astro',
     hooks: {
-      'astro:config:setup': async ({ injectRoute, updateConfig, logger, command, config: astroConfig }) => {
+      'astro:config:setup': async ({
+        injectRoute,
+        updateConfig,
+        logger: localLogger,
+        command,
+        config: astroConfig,
+      }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
         const projectDir = astroConfig.root.pathname;
+        astroBase = astroConfig.base;
+
+        reportError = (message: string) => logger.error(message);
+
+        if (pluginConfig.experimentalPlaygrounds) {
+          playgroundsBase = pluginConfig.experimentalPlaygrounds.playgroundsBase;
+        }
 
         const middlewareFile = path.join(projectDir, 'middleware.stainless.ts');
 
         let vmMiddlewareExport = 'export const MIDDLEWARE = {};';
         if (fs.existsSync(middlewareFile)) {
-          logger.info(`Loading middleware from ${middlewareFile}`);
+          logger.debug(`Loading middleware from ${middlewareFile}`);
           vmMiddlewareExport = `export { default as MIDDLEWARE } from '${middlewareFile}';`;
         }
 
         injectRoute({
-          pattern: `${pluginConfig.basePath}/[...slug].md`,
-          entrypoint: '@stainless-api/docs/MarkdownRoute',
+          pattern: `${pluginConfig.basePath}/[...slug]/index.md`,
+          entrypoint: resolveSrcFile('/plugin/routes/markdown.ts'),
           prerender: command === 'build',
         });
 
-        const astroFile = command === 'build' ? 'DocsStaticRoute' : 'DocsRoute';
+        const astroFile = command === 'build' ? 'DocsStatic' : 'Docs';
         injectRoute({
           pattern: `${pluginConfig.basePath}/[...slug]`,
-          // in prod I think this points to @stainless-starlight/components/docs.astro
-          entrypoint: `@stainless-api/docs/${astroFile}`,
+          entrypoint: resolveSrcFile(`/plugin/routes/${astroFile}.astro`),
           prerender: command === 'build',
         });
 
         injectRoute({
           pattern: pluginConfig.basePath,
-          entrypoint: '@stainless-api/docs/OverviewRoute',
+          entrypoint: resolveSrcFile('/plugin/routes/Overview.astro'),
           prerender: command === 'build',
         });
 
         updateConfig({
           vite: {
-            ssr: {
-              noExternal: ['@stainless-api/ui-primitives'],
-            },
-            optimizeDeps: { include: ['@stainless-api/ui-primitives'] },
             plugins: [
               {
                 name: 'stl-starlight-vite',
-                configureServer(server) {
+                buildStart() {
+                  building = undefined;
+                },
+                async configureServer(server) {
+                  if (playgroundsBase) {
+                    buildPlaygrounds = (await server.ssrLoadModule(playgroundsBase + '/src/build.ts'))
+                      .buildPlaygrounds;
+                  }
+
                   for (const filePath of Object.values(devPaths)) {
                     if (!filePath) {
                       continue;
@@ -197,28 +260,82 @@ async function stlStarlightAstroIntegration(
                   if (id === virtualId) {
                     return resolvedId;
                   }
+                  if (id === 'virtual:stl-playground/unstable-update-language') {
+                    return resolveSrcFile('plugin/languages.ts');
+                  }
+                  if (id === 'virtual:stl-playground/create') {
+                    return fileURLToPath(
+                      new URL(
+                        pluginConfig.experimentalPlaygrounds
+                          ? path.join(playgroundsBase!, '/src/create.tsx')
+                          : './globalJs/create-playground.shim.ts',
+                        import.meta.url,
+                      ),
+                    );
+                  }
+                  if (id === 'virtual:stl-playground/data') {
+                    return fileURLToPath(
+                      new URL(
+                        pluginConfig.experimentalPlaygrounds
+                          ? './globalJs/playground-data.ts'
+                          : './globalJs/playground-data.shim.ts',
+                        import.meta.url,
+                      ),
+                    );
+                  }
+                  if (id.startsWith('virtual:stl-playground/')) {
+                    const result = path.join(
+                      this.environment.getTopLevelConfig().cacheDir,
+                      'stl-playground',
+                      id.slice('virtual:stl-playground/'.length),
+                    );
+                    const config = this.environment.getTopLevelConfig();
+                    return startPlaygroundsBuild(path.join(config.cacheDir, 'stl-playground'))?.then(
+                      () => result,
+                    );
+                  }
                 },
                 load(id) {
                   if (id === resolvedId) {
                     return [
                       buildVirtualModuleString({
-                        BASE_PATH: pluginConfig.basePath,
+                        BASE_PATH: path.posix.join(astroConfig.base, pluginConfig.basePath),
                         CMS_PORT,
-                        EXCLUDE_LANGUAGES: pluginConfig.excludeLanguages,
+                        EXCLUDE_LANGUAGES: ['php', ...pluginConfig.excludeLanguages],
                         DEFAULT_LANGUAGE: pluginConfig.defaultLanguage,
                         BREADCRUMB_CONFIG: pluginConfig.breadcrumbs,
                         EXPAND_RESOURCES: pluginConfig.expandResources,
                         HIGHLIGHT_THEMES: pluginConfig.highlighting.themes,
                         CONTENT_PANEL_LAYOUT: pluginConfig.contentPanel.layout,
                         EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: pluginConfig.experimentalCollapsibleSnippets,
+                        EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS:
+                          pluginConfig.experimentalCollapsibleMethodDescriptions,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
-                        SEARCH: pluginConfig.search,
-                      }),
+                        ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
+                        EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
+                        EXPERIMENTAL_REQUEST_BUILDER: pluginConfig.experimentalRequestBuilder,
+                        STAINLESS_PROJECT: version.stainlessProject,
+                      } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
                   }
                 },
               },
+              prebundleWorkers({
+                include: [
+                  '**/typescript/runner*',
+                  '**/typescript/worker*',
+                  '**/pyright.worker*',
+                  '**/python/pyodide*',
+                ],
+                configureEsBuild(_, opts) {
+                  opts.external ??= [];
+                  opts.external.push('url');
+                  opts.loader ??= {};
+                  opts.loader['.wasm'] = 'dataurl';
+                  return opts;
+                },
+              }),
             ],
           },
         });
@@ -226,6 +343,29 @@ async function stlStarlightAstroIntegration(
       'astro:server:done': async () => {
         await cmsServer.destroy();
       },
+      'astro:build:start'({ logger }) {
+        collectedErrors = [];
+        reportError = (message: string) => {
+          logger.error(message);
+          collectedErrors!.push(message);
+        };
+      },
+      'astro:build:done': async ({ dir, logger }) => {
+        const dist = fileURLToPath(dir);
+        const stainlessDir = path.join(dist, '_stainless');
+        await mkdir(stainlessDir, { recursive: true });
+        if (collectedErrors) {
+          for (const error of collectedErrors) {
+            logger.error(error);
+          }
+          collectedErrors = null;
+        }
+
+        const manifest = {
+          astroBase,
+        };
+        await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
+      },
     },
   };
 }
@@ -241,15 +381,20 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
         command,
         config: starlightConfig,
         astroConfig,
-        logger,
+        logger: localLogger,
       }) => {
         if (command !== 'build' && command !== 'dev') {
           return;
         }
 
+        const logger = getSharedLogger({ fallback: localLogger });
+
         const configParseResult = parseStarlightPluginConfig(someUserConfig, command);
         if (configParseResult.result === 'error') {
-          logger.error(configParseResult.message);
+          const errorLines = configParseResult.message.split('\n');
+          for (const line of errorLines) {
+            logger.error(line);
+          }
           process.exit(1);
         }
         const config = configParseResult.config;
@@ -260,17 +405,30 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           addIntegration(react());
         }
 
+        if ('apiKey' in config.specRetrieverConfig) {
+          if (!config.specRetrieverConfig.apiKey) {
+            logger.info(`Stainless credentials not loaded`);
+          } else if (config.specRetrieverConfig.apiKey.source === 'explicit-config') {
+            logger.info(`Stainless credentials loaded from user config`);
+          } else if (config.specRetrieverConfig.apiKey.source === 'environment-variable') {
+            logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
+          } else if (config.specRetrieverConfig.apiKey.source === 'cli') {
+            logger.info('Stainless credentials loaded from `stl` CLI');
+          }
+        }
+
         if (
           command === 'build' &&
           config.specRetrieverConfig.kind === 'local_spec_server_with_remote_files'
         ) {
           await buildAlgoliaIndex({
             version: config.specRetrieverConfig.version,
-            apiKey: config.specRetrieverConfig.apiKey,
+            apiKey: config.specRetrieverConfig.apiKey.value,
+            logger,
           });
         }
 
-        addIntegration(await stlStarlightAstroIntegration(config));
+        addIntegration(await stlStarlightAstroIntegration(config, logger));
 
         if (starlightConfig.sidebar) {
           // for pagination (https://starlight.astro.build/reference/configuration/#pagination) to work correctly
@@ -281,21 +439,25 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           }
         }
 
-        const currentExpressiveCode =
+        const expressiveCodeConfig =
           typeof starlightConfig.expressiveCode === 'object' ? starlightConfig.expressiveCode : {};
-        updateConfig({
-          expressiveCode: {
-            ...currentExpressiveCode,
-            themes: [...(currentExpressiveCode.themes || []), 'github-light', 'github-dark'],
-          },
-        });
+
+        const themes = expressiveCodeConfig.themes
+          ? (expressiveCodeConfig.themes as BundledTheme[])
+          : (['github-light', 'github-dark'] as BundledTheme[]);
 
         updateConfig({
           sidebar: starlightConfig.sidebar,
+          ...(expressiveCodeConfig && {
+            expressiveCode: {
+              ...expressiveCodeConfig,
+              themes,
+            },
+          }),
         });
 
         addRouteMiddleware({
-          entrypoint: '@stainless-api/docs/replaceSidebarPlaceholderMiddleware',
+          entrypoint: resolveSrcFile('/plugin/replaceSidebarPlaceholderMiddleware.ts'),
           order: 'post',
         });
       },
@@ -304,5 +466,5 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 }
 
 // Additional exports we want for Stainless <-> docs integration.
-export { parseStainlessPath } from '@stainless-api/docs-ui/src/routing';
-export { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+export { parseStainlessPath } from '@stainless-api/docs-ui/routing';
+export { renderMarkdown } from '@stainless-api/docs-ui/markdown';

package/plugin/languages.ts

@@ -1,4 +1,4 @@
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import KotlinIcon from './assets/languages/kotlin.svg';
 import RubyIcon from './assets/languages/ruby.svg';
 import TerraformIcon from './assets/languages/terraform.svg';
@@ -7,6 +7,8 @@ import PythonIcon from './assets/languages/python.svg';
 import JavaIcon from './assets/languages/java.svg';
 import GoIcon from './assets/languages/go.svg';
 import CurlIcon from './assets/languages/curl.svg';
+import CSharpIcon from './assets/languages/csharp.svg';
+import CLIIcon from './assets/languages/cli.svg';
 
 export const Languages: Record<
   DocsLanguage,
@@ -29,6 +31,9 @@ export const Languages: Record<
   http: { name: 'HTTP', icon: CurlIcon, alt: 'HTTP logo' },
   terraform: { name: 'Terraform', icon: TerraformIcon, alt: 'Terraform logo' },
   ruby: { name: 'Ruby', icon: RubyIcon, alt: 'Ruby logo' },
+  csharp: { name: 'C#', icon: CSharpIcon, alt: 'C# logo' },
+  cli: { name: 'CLI Tool', icon: CLIIcon, alt: 'CLI logo' },
+  php: { name: 'PHP', icon: CSharpIcon, alt: 'PHP logo' }, // TODO update PHP icon
 };
 
 export function generatePrefix(basePath: string, language: string) {
@@ -44,7 +49,7 @@ export function applyLanguageToLinks(basePath?: string, defaultLanguage?: string
     `[data-stldocs-overview],[data-stldocs-method],a.nav-link[href^='${basePath}']`,
   );
 
-  for (var link of links) {
+  for (const link of links) {
     const href = link.getAttribute('href');
     const prefix = generatePrefix(basePath, language);
     if (href?.startsWith(basePath) && !href?.startsWith(prefix)) {