@stainless-api/docs 0.1.0-beta.7 → 0.1.0-beta.70

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 } 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,24 @@ 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;
 
   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 +144,98 @@ 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;
 
+        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,6 +258,30 @@ 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')
+                          : './create-playground.shim.tsx',
+                        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) {
@@ -204,21 +289,39 @@ async function stlStarlightAstroIntegration(
                       buildVirtualModuleString({
                         BASE_PATH: 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,
+                      } 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 +329,24 @@ 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;
+        }
+      },
     },
   };
 }
@@ -241,15 +362,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 +386,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 +420,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 +447,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,7 @@ 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';
 
 export const Languages: Record<
   DocsLanguage,
@@ -29,6 +30,8 @@ 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' },
+  php: { name: 'PHP', icon: CSharpIcon, alt: 'PHP logo' }, // TODO update PHP icon
 };
 
 export function generatePrefix(basePath: string, language: string) {
@@ -44,7 +47,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)) {

package/plugin/loadPluginConfig.ts

@@ -1,9 +1,12 @@
 import path from 'path';
+import { homedir } from 'os';
+import { existsSync, readFileSync } from 'fs';
 
 import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type { PropertySettingsType } from '@stainless-api/docs-ui/src/contexts';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
 import type { InputFilePaths } from '../plugin/cms/server';
+import { bold } from '../shared/terminalUtils';
 
 export type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
 
@@ -18,7 +21,7 @@ export type VersionUserConfig = {
 type BreadcrumbUserConfig = {
   /**
    * Include the current page in the breadcrumb list.
-   * Defaults to `false`.
+   * Default: `false`
    */
   includeCurrentPage?: boolean;
 };
@@ -26,7 +29,12 @@ type BreadcrumbUserConfig = {
 export type StainlessStarlightUserConfig = {
   /**
    * Optional api key for Stainless API.
-   * If not provided, it will look for the STAINLESS_API_KEY environment variable.
+   * If not provided, we will handle Stainless auth via the `stl` CLI or look for the STAINLESS_API_KEY environment variable.
+   * Precedence:
+   * 1. Explicity `apiKey` option provided
+   * 2. `STAINLESS_API_KEY` environment variable
+   * 3. Login status from the `stl` CLI
+   * 4. Error (no auth found)
    */
   apiKey?: string;
 
@@ -42,8 +50,8 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional mount point for API reference docs.
-   * Defaults to `/api`.
    * Example: `/my-api` → docs available at `/my-api/…`.
+   * @default `/api`
    */
   basePath?: string;
 
@@ -55,8 +63,8 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional language to treat as the default when the user hasn't selected one.
-   * Defaults to `"http"` when none is provided.
-   * Example: `"python"`
+   * Example: `'python'`
+   * @default 'http'
    */
   defaultLanguage?: DocsLanguage;
 
@@ -90,7 +98,7 @@ export type StainlessStarlightUserConfig = {
   contentPanel?: {
     /**
      * Optional layout for the content panel.
-     * Defaults to `"double-pane"`.
+     * @default 'double-pane'
      */
     layout?: ContentLayout;
   };
@@ -100,23 +108,35 @@ export type StainlessStarlightUserConfig = {
    */
   propertySettings?: PropertySettingsType;
 
-  /**
-   * Options to control the documentation site's search functionality
-   */
-  search?: {
-    /**
-     * When set to `true`, the enableAISearch` setting turns on support for
-     * LLM-based conversations with the API documentation
-     */
-    enableAISearch?: boolean;
-  };
-
   /**
    * Enable experimental collapsible code snippets. Snippets will be collapsed by default for
    * single-pane and mobile layouts.
-   * Defaults to `false`.
+   *
+   * @default false
    */
   experimentalCollapsibleSnippets?: boolean;
+
+  /**
+   * Enable experimental collapsible method descriptions. Method descriptions will be
+   * collapsed if their content exceeds a certain length.
+   *
+   * @default false
+   */
+  experimentalCollapsibleMethodDescriptions?: boolean;
+
+  /**
+   * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
+   *
+   * @default true
+   */
+
+  contextMenu?: boolean;
+
+  /**
+   * When set to `import playgrounds from '@stainless-api/playgrounds'`, code snippets will have a "Play" button,
+   * allowing users to edit and run code snippets in their browser.
+   */
+  experimentalPlaygrounds?: { playgroundsBase: string };
 };
 
 export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
@@ -133,15 +153,29 @@ function getLocalFilePaths(command: AstroCommand): InputFilePaths | null {
   if (command !== 'dev') {
     return null;
   }
-  if (!process.env.OPENAPI_PATH || !process.env.STAINLESS_SPEC_PATH) {
+
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const oasPath = process.env.OPENAPI_PATH;
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const configPath = process.env.STAINLESS_CONFIG_PATH;
+
+  if (!oasPath || !configPath) {
     return null;
   }
+
   return {
-    oasPath: resolvePath(process.env.OPENAPI_PATH),
-    configPath: resolvePath(process.env.STAINLESS_SPEC_PATH),
+    oasPath: resolvePath(oasPath),
+    configPath: resolvePath(configPath),
   };
 }
 
+export type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
+
+export type LoadedApiKey = {
+  value: string;
+  source: ApiKeySource;
+};
+
 export type SpecRetrieverConfig =
   | {
       kind: 'external_spec_server';
@@ -152,16 +186,63 @@ export type SpecRetrieverConfig =
       kind: 'local_spec_server_with_files';
       stainlessProject: string;
       devPaths: InputFilePaths;
-      apiKey: string | null;
+      apiKey: LoadedApiKey | null;
       version: VersionUserConfig;
     }
   | {
       kind: 'local_spec_server_with_remote_files';
       stainlessProject: string;
-      apiKey: string;
+      apiKey: LoadedApiKey;
       version: VersionUserConfig;
     };
 
+function parseAuthJson(authJsonStr: string) {
+  let json: unknown;
+  try {
+    json = JSON.parse(authJsonStr);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  } catch (_error) {
+    return null;
+  }
+
+  if (typeof json !== 'object' || json === null) {
+    return null;
+  }
+  if (!('access_token' in json)) {
+    return null;
+  }
+  const accessToken = json['access_token'];
+  if (typeof accessToken !== 'string') {
+    return null;
+  }
+  return accessToken;
+}
+
+function loadApiKey(configValue: string | undefined): LoadedApiKey | null {
+  if (typeof configValue === 'string') {
+    return { value: configValue, source: 'explicit-config' };
+  }
+  if (process.env.STAINLESS_API_KEY) {
+    return { value: process.env.STAINLESS_API_KEY, source: 'environment-variable' };
+  }
+
+  const homeDirPath = homedir();
+
+  const authJsonPath = path.join(homeDirPath, '.config', 'stainless', 'auth.json');
+
+  if (!existsSync(authJsonPath)) {
+    return null;
+  }
+
+  const authJsonStr = readFileSync(authJsonPath, 'utf-8');
+  const accessToken = parseAuthJson(authJsonStr);
+  if (!accessToken) {
+    return null;
+  }
+
+  return { value: accessToken, source: 'cli' };
+}
+
 function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: AstroCommand) {
   const configWithDefaults = {
     basePath: partial.basePath ?? '/api',
@@ -181,15 +262,16 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
       layout: partial.contentPanel?.layout ?? 'double-pane',
     },
     experimentalCollapsibleSnippets: partial.experimentalCollapsibleSnippets ?? false,
+    experimentalCollapsibleMethodDescriptions: partial.experimentalCollapsibleMethodDescriptions ?? false,
     propertySettings: {
       types: partial.propertySettings?.types ?? 'rich',
       collapseDescription: partial.propertySettings?.collapseDescription ?? true,
+      showTitle: partial.propertySettings?.showTitle ?? false,
       expandDepth: partial.propertySettings?.expandDepth ?? 0,
       includeModelProperties: partial.propertySettings?.includeModelProperties ?? true,
     },
-    search: {
-      enableAISearch: partial.search?.enableAISearch ?? false,
-    },
+    contextMenu: partial.contextMenu ?? true,
+    experimentalPlaygrounds: partial.experimentalPlaygrounds ?? undefined,
   };
 
   function getSpecRetrieverConfig(): SpecRetrieverConfig {
@@ -205,7 +287,7 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
       throw new Error('You must provide a stainlessProject when using Stainless Starlight');
     }
 
-    const apiKey = partial.apiKey ?? process.env.STAINLESS_API_KEY ?? null;
+    const apiKey = loadApiKey(partial.apiKey);
 
     const version = {
       stainlessProject: partial.stainlessProject,
@@ -226,7 +308,14 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
 
     if (!apiKey) {
       throw new Error(
-        'Please provide a Stainless API key via the STAINLESS_API_KEY environment variable or the apiKey option in the Stainless Starlight config.',
+        [
+          bold(
+            'No Stainless credentials found. Please choose one of the following options to authenticate with Stainless:',
+          ),
+          '- Run `stl auth login` to authenticate via the Stainless CLI',
+          '- Provide a Stainless API key via the `STAINLESS_API_KEY` environment variable (eg. in a .env file)',
+          '- Set the `apiKey` option in the Stainless Docs config',
+        ].join('\n'),
       );
     }
 
@@ -249,11 +338,11 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
 export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConfig>;
 
 /*
- The goal of the code in this file is to take a user's config and normalize it. 
+ The goal of the code in this file is to take a user's config and normalize it.
  Specifically: we want a single complete config format used throughout the internals of the plugin.
 
  We've tried to avoid any config values being optional/undefined. To accomplish this:
- - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api
  - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
  - We prefer empty arrays over undefined/null
 */

package/plugin/middlewareBuilder/stainlessMiddleware.d.ts

@@ -1,4 +1,4 @@
-import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/src/components/sdk';
+import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/components/sdk';
 
 export type StlStarlightMiddleware = {
   transformRequestSnippet?: TransformRequestSnippetFn;