@stainless-api/docs 0.1.0-beta.14 → 0.1.0-beta.16

package/plugin/index.ts

@@ -1,6 +1,6 @@
 import react from '@astrojs/react';
 import type { StarlightPlugin } from '@astrojs/starlight/types';
-import type { AstroIntegration } from 'astro';
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
 import { config } from 'dotenv';
 import getPort from 'get-port';
 import { startDevServer } from './cms/server';
@@ -23,11 +23,15 @@ import {
 import { buildVirtualModuleString } from '../shared/virtualModule';
 import path from 'path';
 import fs from 'fs';
+import { getSharedLogger } from '../shared/getSharedLogger';
+import { resolveSrcFile } from '../resolveSrcFile';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
 
-config();
+config({
+  quiet: true,
+});
 
 let sidebarIdCounter = 0;
 
@@ -108,6 +112,7 @@ 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.
@@ -119,9 +124,10 @@ async function stlStarlightAstroIntegration(
 
   const cmsServer = await startDevServer({
     port: CMS_PORT,
-    apiKey,
+    apiKey: apiKey.value,
     version,
     devPaths,
+    logger: stlStarlightPluginLogger,
     getGeneratedSidebarConfig: (id: number) => {
       const config = sidebarConfigs.get(id);
       if (!config) {
@@ -134,55 +140,43 @@ async function stlStarlightAstroIntegration(
   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;
 
         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',
         });
 
-        // Remove starlight callout syntax in favor of our own callout component
-        // updateConfig always deeply merges arrays so we need to mutate remarkPlugins directly
-        // in order to remove plugins that starlight added
-        astroConfig.markdown.remarkPlugins = astroConfig.markdown.remarkPlugins.filter((plugin, i, arr) => {
-          if (typeof plugin !== 'function') return true;
-          // remove:
-          // 1. remarkDirective plugin
-          if (plugin.name === 'remarkDirective') return false;
-          // 2. directly followed by remarkAsides plugin (inner function named 'attacher')
-          if (plugin.name === 'attacher') {
-            const prev = arr[i - 1];
-            if (typeof prev === 'function' && prev.name === 'remarkDirective') return false;
-          }
-          // 3. remarkDirectivesRestoration plugin
-          if (plugin.name === 'remarkDirectivesRestoration') return false;
-          return true;
-        });
-
         updateConfig({
           vite: {
             ssr: {
@@ -231,7 +225,6 @@ async function stlStarlightAstroIntegration(
                         EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: pluginConfig.experimentalCollapsibleSnippets,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         SEARCH: pluginConfig.search,
-                        INCLUDE_AI_DROPDOWN_OPTIONS: pluginConfig.includeAIDropdownOptions,
                       }),
                       vmMiddlewareExport,
                     ].join('\n');
@@ -260,15 +253,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;
@@ -279,17 +277,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
@@ -314,7 +325,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
         });
 
         addRouteMiddleware({
-          entrypoint: '@stainless-api/docs/replaceSidebarPlaceholderMiddleware',
+          entrypoint: resolveSrcFile('/plugin/replaceSidebarPlaceholderMiddleware.ts'),
           order: 'post',
         });
       },

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 { 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,7 +50,7 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional mount point for API reference docs.
-   * Defaults to `/api`.
+   * Default: `/api`
    * Example: `/my-api` → docs available at `/my-api/…`.
    */
   basePath?: string;
@@ -55,7 +63,7 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional language to treat as the default when the user hasn't selected one.
-   * Defaults to `"http"` when none is provided.
+   * Default: `"http"`
    * Example: `"python"`
    */
   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;
   };
@@ -107,6 +115,8 @@ export type StainlessStarlightUserConfig = {
     /**
      * When set to `true`, the enableAISearch` setting turns on support for
      * LLM-based conversations with the API documentation
+     *
+     * Default: `false`
      */
     enableAISearch?: boolean;
   };
@@ -114,16 +124,10 @@ export type StainlessStarlightUserConfig = {
   /**
    * Enable experimental collapsible code snippets. Snippets will be collapsed by default for
    * single-pane and mobile layouts.
-   * Defaults to `false`.
+   *
+   * Default: `false`
    */
   experimentalCollapsibleSnippets?: boolean;
-
-  /**
-   * When set to `true`, a dropdown button will be included on all pages to allow users to
-   * view or send markdown to an LLM.
-   * Defaults to `false`.
-   */
-  includeAIDropdownOptions?: boolean;
 };
 
 export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
@@ -140,15 +144,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';
@@ -159,16 +177,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',
@@ -197,7 +262,6 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
     search: {
       enableAISearch: partial.search?.enableAISearch ?? false,
     },
-    includeAIDropdownOptions: partial.includeAIDropdownOptions ?? false,
   };
 
   function getSpecRetrieverConfig(): SpecRetrieverConfig {
@@ -213,7 +277,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,
@@ -234,7 +298,12 @@ 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'),
       );
     }
 

package/plugin/react/Routing.tsx

@@ -7,7 +7,7 @@ import remarkGfmAlerts from 'remark-github-alerts';
 import type { MarkdownHeading } from 'astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { LanguageNames, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
 
 import {
   generateRouteList,
@@ -48,15 +48,15 @@ import {
   HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
-  INCLUDE_AI_DROPDOWN_OPTIONS,
 } from 'virtual:stl-starlight-virtual-module';
+// TODO (eventually): this file should really probably only be importing from the starlight virtual module
+import { ENABLE_CONTEXT_MENU } from 'virtual:stl-docs-virtual-module';
 import style from '@stainless-api/docs-ui/src/style';
 import { createHighlighter, type BundledLanguage, type BundledTheme, type HighlighterGeneric } from 'shiki';
 import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
-import clsx from 'clsx';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
 import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
-import { APIReferenceAIDropdown } from '../../stl-docs/components/APIReferenceAIDropdown';
+import { AIDropdown } from '../../stl-docs/components/AIDropdown';
 
 export function generateDocsRoutes(spec: SDKJSON.Spec) {
   const paths = generateRouteList({
@@ -121,7 +121,6 @@ export function buildSidebar(
 
       const meths: SidebarEntry[] = Object.values(resource.methods ?? [])
         .filter((method) => spec.decls?.[language]?.[method.stainlessPath])
-        .toSorted((first, second) => first.name.localeCompare(second.name))
         .map((method) => ({
           type: 'link',
           isCurrent: current === method.stainlessPath,
@@ -182,23 +181,23 @@ export function SDKSelectReactComponent({
       <DropdownTrigger
         className="dropdown-toggle"
         type="button"
-        id="stldocs-snippet-title-button"
+        id="stl-docs-snippet-title-button"
         aria-expanded="false"
         withChevron
       >
         <SDKIcon language={getLanguageSnippet(selected)} size={16} />
-        <span className={clsx('stl-snippet-dropdown-button-text', selected)}>{selected}</span>
+        <span className="stl-snippet-dropdown-button-text">{LanguageNames[selected]}</span>
       </DropdownTrigger>
       <DropdownMenu
         className="dropdown-menu stl-sdk-select-dropdown-menu"
         position="below"
-        aria-labelledby="stldocs-snippet-title-button"
+        aria-labelledby="stl-docs-snippet-title-button"
       >
         {languages.map((item) => (
           <DropdownItem key={item} value={item} selected={item === selected}>
             <div>
               <SDKIcon language={getLanguageSnippet(item)} size={16} />
-              <span className={clsx('stl-snippet-dropdown-button-text', item)}>{item}</span>
+              <span className="stl-snippet-dropdown-button-text">{LanguageNames[item]}</span>
             </div>
           </DropdownItem>
         ))}
@@ -324,7 +323,7 @@ export function RenderSpec({
       >
         <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
-            {kind === 'http_method' ? (
+            {
               <div className="stldocs-root stl-ui-not-prose">
                 <div className="stl-page-nav-container">
                   <SDKBreadcrumbs
@@ -333,27 +332,18 @@ export function RenderSpec({
                     basePath={BASE_PATH}
                     config={BREADCRUMB_CONFIG}
                   />
-                  {INCLUDE_AI_DROPDOWN_OPTIONS && <APIReferenceAIDropdown />}
+                  {ENABLE_CONTEXT_MENU && <AIDropdown />}
                 </div>
-                <SDKMethod
-                  method={resource.methods[parsed.method]}
-                  transformRequestSnippet={transformRequestSnippet}
-                />
-              </div>
-            ) : (
-              <div className="stldocs-root stl-ui-not-prose">
-                <div className="stl-page-nav-container">
-                  <SDKBreadcrumbs
-                    spec={spec as SDKJSON.Spec}
-                    currentPath={currentPath}
-                    basePath={BASE_PATH}
-                    config={BREADCRUMB_CONFIG}
+                {kind === 'http_method' ? (
+                  <SDKMethod
+                    method={resource.methods[parsed.method]}
+                    transformRequestSnippet={transformRequestSnippet}
                   />
-                  {INCLUDE_AI_DROPDOWN_OPTIONS && <APIReferenceAIDropdown />}
-                </div>
-                <SDKOverview resource={resource} />
+                ) : (
+                  <SDKOverview resource={resource} />
+                )}
               </div>
-            )}
+            }
           </MarkdownProvider>
         </NavigationProvider>
       </ComponentProvider>

package/plugin/routes/Docs.astro

@@ -21,6 +21,12 @@ if (!route) {
   throw new Error("No such route");
 }
 
+// PageTitle override will skip rendering the default Starlight title
+// @ts-expect-error - _stlStarlightPage isn't typed yet
+Astro.locals._stlStarlightPage = {
+  skipRenderingStarlightTitle: route.props.kind === 'readme' ? false : true,
+}
+
 const readmeContent = await getReadmeContent(spec, route.props.language);
 const readme =
   route.props.kind === "readme"
@@ -69,11 +75,6 @@ if (readme) {
     tableOfContents: ["resource", "readme"].includes(props.kind)
       ? { maxHeadingLevel: 6 }
       : false,
-    // @ts-ignore
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      ...props,
-    },
   }}
 >
   {
@@ -107,17 +108,7 @@ if (readme) {
           [data-has-sidebar]:not([data-has-toc]) .sl-container {
             max-width: 1428px;
           }
-
-          .content-panel:nth-of-type(1) {
-            display: none;
-          }
-          .content-panel:nth-of-type(2) .stl-page-nav-container {
-            display: none;
-          }
-
-          .content-panel:nth-of-type(2) .stldocs-root .stl-page-nav-container {
-            display: flex;
-          }
+          
         </style>
       </div>
     ) : (

package/plugin/routes/Overview.astro

@@ -1,6 +1,6 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { BASE_PATH, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { cmsClient } from '../cms/client';
 import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
 import { RenderLibraries, RenderSpecOverview, type SpecMetadata } from '../react/Routing';
@@ -12,6 +12,12 @@ const metadata = languages
   .filter((language) => !['http', 'terraform'].includes(language) && spec.metadata[language])
   .filter((language) => !EXCLUDE_LANGUAGES.includes(language))
   .map((language) => [language, spec.metadata[language]]) as SpecMetadata;
+
+// PageTitle override will skip rendering the default Starlight title
+// @ts-expect-error - _stlStarlightPage isn't typed yet
+Astro.locals._stlStarlightPage = {
+  hasMarkdownRoute: false,
+};
 ---
 
 <StarlightPage
@@ -19,10 +25,6 @@ const metadata = languages
     title: 'API Reference',
     pagefind: false,
     tableOfContents: false,
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      language: 'http',
-    },
   }}
 >
   <h3>Libraries</h3>