@stainless-api/playgrounds 0.0.1-beta.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @stainless-api/playgrounds
+
+## 0.0.1-beta.0
+
+### Patch Changes
+
+- 2e1639a: prep for release
+- Updated dependencies [239e28c]
+- Updated dependencies [2e1639a]
+- Updated dependencies [ddc4593]
+- Updated dependencies [2e1639a]
+- Updated dependencies [2e1639a]
+  - @stainless-api/docs-ui@0.1.0-beta.44
+  - @stainless/sdk-json@0.1.0-beta.1
+  - @stainless-api/ui-primitives@0.1.0-beta.33

package/README.md

@@ -0,0 +1,23 @@
+# `@stainless-api/playgrounds`
+
+This is a plugin for `@stainless-api/docs` that adds a "Play" button to code snippets, allowing users to edit and run them in their browser.
+
+## Usage
+
+```diff
++ import playgrounds from '@stainless-api/playgrounds';
+  // ...
+  export default defineConfig({
+    integrations: [
+      stainlessDocs({
+        apiReference: {
++         experimentalPlaygrounds: playgrounds,
+        },
+      }),
+    ],
+  });
+```
+
+## Notes
+
+If you have a Python SDK you will need python3 installed (and python3-virtualenv on Debian)

package/eslint.config.js

@@ -0,0 +1,2 @@
+import { config } from '@stainless/eslint-config/astro';
+export default config;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@stainless-api/playgrounds",
+  "version": "0.0.1-beta.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "vite": ">=6.2.1"
+  },
+  "dependencies": {
+    "@codemirror/autocomplete": "^6.18.7",
+    "@codemirror/commands": "^6.8.1",
+    "@codemirror/lang-javascript": "^6.2.4",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/language": "^6.11.3",
+    "@codemirror/legacy-modes": "^6.5.1",
+    "@codemirror/lint": "^6.8.5",
+    "@codemirror/lsp-client": "^6.1.2",
+    "@codemirror/search": "^6.5.11",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/theme-one-dark": "^6.1.3",
+    "@codemirror/view": "^6.38.2",
+    "@preact/signals-core": "^1.12.1",
+    "@replit/codemirror-vscode-keymap": "^6.0.2",
+    "@shikijs/types": "^3.15.0",
+    "@stainless-api/codemirror-ts": "^3.0.1",
+    "@typescript/vfs": "^1.6.1",
+    "clsx": "^2.1.1",
+    "corepack": "^0.34.3",
+    "dompurify": "^3.2.6",
+    "js-tokens": "^9.0.1",
+    "lines-and-columns": "^2.0.4",
+    "lucide-react": "^0.555.0",
+    "marked": "^16.0.0",
+    "shiki": "^3.19.0",
+    "source-map": "^0.7.6",
+    "type-fest": "^5.3.0",
+    "unenv": "^1.10.0",
+    "vite-plugin-prebundle-workers": "^0.2.0",
+    "vscode-languageserver-protocol": "^3.17.5",
+    "@stainless-api/docs-ui": "0.1.0-beta.44",
+    "@stainless-api/ui-primitives": "0.1.0-beta.33",
+    "@stainless/sdk-json": "^0.1.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "is-callable": "^1.2.7",
+    "pyodide": "^0.28.2",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "typescript": "5.9.3",
+    "vite": "^6.4.1",
+    "@stainless/eslint-config": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "check:types": "tsc --noEmit",
+    "test": "node --test"
+  }
+}

package/src/Logs.tsx

@@ -0,0 +1,216 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type PropsWithChildren,
+} from 'react';
+import { effect } from '@preact/signals-core';
+import style from '@stainless-api/docs-ui/style';
+import { Bug, ChevronRight, CircleAlert, Info, LogsIcon, Terminal, Trash, TriangleAlert } from 'lucide-react';
+import { LogsContext } from './logs-context';
+import { Panel } from './Panel';
+import { Button } from '@stainless-api/ui-primitives';
+
+export type JSLogType =
+  | 'error'
+  | 'warn'
+  | 'log'
+  | 'info'
+  | 'debug'
+  | 'dir'
+  | 'trace'
+  | 'group'
+  | 'groupCollapsed'
+  | 'groupEnd';
+export type LogType = JSLogType | 'stdout' | 'stderr';
+export type Log =
+  | {
+      type: LogType;
+      parts: (string | Part)[];
+    }
+  | { type: 'clear'; parts?: undefined };
+export type Logger = (log: Log) => void;
+export type Part = {
+  css: string | undefined;
+  value: string | Part[];
+  expandHandle?: string;
+  id?: string;
+  lowPriority?: boolean;
+};
+export type StateLog =
+  | {
+      type: LogType;
+      parts: (string | StatePart)[];
+    }
+  | { type: 'clear'; parts?: undefined };
+export type StatePart = {
+  css: string | undefined;
+  value: string | StatePart[];
+  handle?: { expand(): Promise<StatePart[]>; free(): void; id?: string };
+  lowPriority?: boolean;
+};
+
+function InlineStyled({ style, children }: PropsWithChildren<{ style: string | undefined }>) {
+  const ref = useRef<HTMLSpanElement>(null);
+  useLayoutEffect(() => {
+    if (style === undefined) {
+      ref.current?.removeAttribute('style');
+    } else {
+      ref.current?.setAttribute('style', style);
+    }
+  }, [style]);
+  return <span ref={ref}>{children}</span>;
+}
+const ParentsContext = createContext<(string | undefined)[]>([]);
+const SiblingsContext = createContext<number>(0);
+function RenderPart({ part }: { part: StatePart }) {
+  const parents = useContext(ParentsContext);
+  const siblings = useContext(SiblingsContext);
+  const [open, setOpen] = useState(
+    !part.lowPriority &&
+      (!part.handle?.id || !parents.includes(part.handle?.id)) &&
+      parents.length < 5 &&
+      siblings < 10,
+  );
+  const [children, setChildren] = useState<StatePart[]>();
+  useEffect(() => {
+    return () => children?.forEach((e) => e.handle?.free());
+  }, [children]);
+  useLayoutEffect(() => {
+    if (open) {
+      part.handle?.expand().then((e) => {
+        if (children?.length && !e.length) return;
+        setChildren(e);
+      });
+    }
+  }, [open]);
+  const value =
+    typeof part.value === 'string'
+      ? part.value
+      : part.value.map((part, i) => <RenderPart key={i} part={part} />);
+  return (
+    <ParentsContext value={[...parents, part.handle?.id]}>
+      <InlineStyled style={part.css}>
+        {part.handle === undefined ? (
+          value
+        ) : (
+          <>
+            <button
+              className={
+                'playground-logs-object-toggle' + (open ? ' playground-logs-object-toggle-open' : '')
+              }
+              title={open ? 'Collapse' : 'Open'}
+              type="button"
+              onClick={() => {
+                setOpen(!open);
+              }}
+            >
+              <ChevronRight className={style.Icon} size={16} />
+            </button>
+            <span
+              onClick={() => {
+                setOpen(!open);
+              }}
+            >
+              {value}
+            </span>
+          </>
+        )}
+      </InlineStyled>
+      {open && children ? (
+        <div className="playground-logs-object-properties">
+          <SiblingsContext value={children.length}>
+            {children.map((e, i) => (
+              <RenderPart part={e} key={i} />
+            ))}
+          </SiblingsContext>
+        </div>
+      ) : null}
+    </ParentsContext>
+  );
+}
+function LogContent({ content: { type, parts } }: { content: StateLog }) {
+  const Icon =
+    type === 'debug'
+      ? Bug
+      : type === 'error'
+        ? CircleAlert
+        : type === 'info'
+          ? Info
+          : type === 'warn'
+            ? TriangleAlert
+            : 'span';
+  return (
+    <li className={'playground-log-' + type}>
+      <Icon className={style.Icon} />{' '}
+      <span className={'playground-logs-content'}>
+        {type === 'clear'
+          ? 'Logs were cleared.'
+          : parts.map((part, i) => (typeof part === 'string' ? part : <RenderPart key={i} part={part} />))}
+      </span>
+    </li>
+  );
+}
+
+export function Logs() {
+  const logsSignal = useContext(LogsContext)!;
+  const logLines = useSyncExternalStore<StateLog[]>(
+    (onChange) => {
+      let changeQueued;
+      return effect(
+        () => (
+          logsSignal.valueOf(),
+          (changeQueued ||= setTimeout(() => {
+            onChange();
+            changeQueued = null;
+          }, 10))
+        ),
+      );
+    },
+    () => logsSignal.peek(),
+  );
+  const logsRef = useRef<HTMLUListElement>(null);
+  useEffect(() => {
+    return clearTimeout.bind(
+      null,
+      setTimeout(() => {
+        const logs = logsRef.current!;
+        logs.scrollTo({
+          top: logs.scrollHeight,
+          behavior: 'smooth',
+        });
+      }, 100),
+    );
+  }, [logLines]);
+  return (
+    <Panel
+      title="Logs"
+      icon={LogsIcon}
+      actions={
+        <Button
+          onClick={() => (logsSignal.value = [])}
+          aria-label="Clear Logs"
+          title="Clear Logs"
+          variant="outline"
+        >
+          <Trash size={16} className={style.Icon} />
+        </Button>
+      }
+    >
+      <ul ref={logsRef} className="playground-logs playground-panel-content">
+        {logLines.length ? (
+          logLines.map((e, i) => <LogContent key={i} content={e} />)
+        ) : (
+          <li className="playground-logs-blankslate">
+            <Terminal />
+            <span>No logs yet!</span>
+          </li>
+        )}
+      </ul>
+    </Panel>
+  );
+}

package/src/Panel.tsx

@@ -0,0 +1,21 @@
+import { type PropsWithChildren } from 'react';
+import style from '@stainless-api/docs-ui/style';
+import { LucideIcon } from 'lucide-react';
+
+export function Panel({
+  title,
+  icon: Icon,
+  children,
+  actions,
+}: PropsWithChildren<{ title: string; icon: LucideIcon; actions?: React.ReactNode }>) {
+  return (
+    <div className="playground-panel">
+      <div className="playground-panel-header">
+        <Icon size={16} className={style.Icon} />
+        <h5 className="playground-panel-title">{title}</h5>
+        {actions}
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/PlaygroundPanelWrapper.tsx

@@ -0,0 +1,5 @@
+import { PropsWithChildren } from 'react';
+
+export function PlaygroundPanelWrapper({ children }: PropsWithChildren) {
+  return <div className="playground-panel-wrapper">{children}</div>;
+}

package/src/build-py-types.ts

@@ -0,0 +1,152 @@
+import { promises as fs, globSync } from 'fs';
+import path, { dirname, resolve } from 'path';
+import os from 'os';
+import { glob, readdir, realpath, writeFile } from 'fs/promises';
+import type data from 'virtual:stl-playground/python.json';
+import { execCommand } from './util';
+import { createRequire } from 'module';
+
+export async function buildPythonTypes(typesPath: string, installPackage: string) {
+  const tmpDir = await realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'py-types-')));
+
+  try {
+    const pyrightPromise = (async () => {
+      await fs.writeFile(path.join(tmpDir, 'package.json'), '{}');
+      await execCommand(
+        process.execPath,
+        [
+          resolve(dirname(createRequire(import.meta.url).resolve('corepack/package.json')), 'dist/pnpm.js'),
+          'install',
+          'pyright',
+        ],
+        {
+          cwd: tmpDir,
+        },
+      );
+      return { pyright: path.join(tmpDir, 'node_modules', '.bin', 'pyright') };
+    })();
+    const venvPromise = (async () => {
+      try {
+        await execCommand('python3', ['-m', 'venv', '.'], { cwd: tmpDir });
+      } catch (e) {
+        throw new Error(
+          'Failed to set up virtual environment for playground build. Do you have Python installed?',
+          {
+            cause: e,
+          },
+        );
+      }
+      const venvBin = path.join(tmpDir, 'bin');
+      const pip = path.join(venvBin, 'pip');
+      return { pip };
+    })();
+    const initialWheelsDirPromise = (async () => {
+      const initialWheelsDir = path.join(tmpDir, 'wheels');
+      await fs.mkdir(initialWheelsDir);
+      return { initialWheelsDir };
+    })();
+    const pkgsDirPromise = (async () => {
+      const pkgsDir = path.join(tmpDir, 'pkgs');
+      await fs.mkdir(pkgsDir);
+      return { pkgsDir };
+    })();
+    const wheelPathPromise = (async () => {
+      const [{ initialWheelsDir }, { pip }] = await Promise.all([initialWheelsDirPromise, venvPromise]);
+      await execCommand(
+        pip,
+        ['wheel', '--no-deps', '-w', 'wheels', installPackage.replace(/^pip install /, '')],
+        {
+          cwd: tmpDir,
+        },
+      );
+      const wheelPath = (await readdir(initialWheelsDir))[0]!;
+      return { wheelPath, wheelsDir: initialWheelsDir };
+    })();
+    const richPromise = (async () => {
+      const response = await fetch(
+        'https://files.pythonhosted.org/packages/e3/30/3c4d035596d3cf444529e0b2953ad0466f6049528a879d27534700580395/rich-14.1.0-py3-none-any.whl',
+      );
+      if (!response.ok) {
+        throw new Error(`Failed to download wheel: ${response.statusText}`);
+      }
+      const { wheelsDir } = await wheelPathPromise;
+      writeFile(path.join(wheelsDir, 'rich-14.1.0-py3-none-any.whl'), await response.bytes());
+    })();
+    const packagesPromise = (async () => {
+      const [{ pip }] = await Promise.all([venvPromise, pkgsDirPromise, richPromise, wheelPathPromise]);
+
+      await execCommand(
+        pip,
+        [
+          'install',
+          '--target',
+          'pkgs',
+          ...globSync('wheels/*', {
+            cwd: tmpDir,
+          }),
+        ],
+        { cwd: tmpDir },
+      );
+
+      const packages = globSync('pkgs/*/__init__.py', { cwd: tmpDir }).map((p) =>
+        path.basename(path.dirname(p)),
+      );
+      return { packages };
+    })();
+
+    const [{ packages }, { pyright }, { wheelsDir, wheelPath }] = await Promise.all([
+      packagesPromise,
+      pyrightPromise,
+      wheelPathPromise,
+    ]);
+
+    await Promise.all(
+      packages.map((pkg) =>
+        execCommand(pyright, ['--createstub', pkg], {
+          cwd: tmpDir,
+          env: { PYTHONPATH: 'pkgs' },
+        }),
+      ),
+    );
+
+    const typingsDir = path.join(tmpDir, 'typings');
+    const files: Record<string, string> = {};
+    const readPromises: Promise<void>[] = [];
+    for await (const file of glob('**/*', { cwd: typingsDir, withFileTypes: true })) {
+      if (!(file.isFile() || file.isSymbolicLink())) continue;
+      const readPromise = (async () => {
+        const fullPath = path.join(file.parentPath, file.name);
+        const content = await fs.readFile(fullPath, 'utf-8');
+        const cleanedContent = content.replace(
+          '"""\nThis type stub file was generated by pyright.\n"""\n',
+          '',
+        );
+        const targetPath = `/play/.venv/lib/site-packages/${path.relative(typingsDir, fullPath)}`;
+        files[targetPath] = cleanedContent;
+      })();
+      readPromises.push(readPromise);
+      readPromise.catch(() => {});
+    }
+
+    await Promise.all([
+      ...readPromises,
+      (async () => {
+        await fs.rm(path.join(typesPath, 'python'), { recursive: true, force: true });
+        await fs.mkdir(path.join(typesPath, 'python'));
+      })(),
+    ]);
+
+    await Promise.all([
+      fs.copyFile(path.join(wheelsDir, wheelPath), path.join(typesPath, 'python', 'wheel.whl')),
+      fs.writeFile(
+        path.join(typesPath, 'python.json'),
+        JSON.stringify({
+          files: files,
+          wheel: wheelPath,
+        } satisfies typeof data),
+      ),
+    ]);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}

package/src/build-ts-types.ts

@@ -0,0 +1,70 @@
+import { promises as fs } from 'fs';
+import { readdirSync, readFileSync, realpathSync, statSync } from 'fs';
+import path, { dirname, resolve } from 'path';
+import os from 'os';
+import { createRequire } from 'module';
+import { execCommand } from './util';
+
+export async function buildTypescriptTypes(typesPath: string, installCommand: string) {
+  const tmpDir = realpathSync(await fs.mkdtemp(path.join(os.tmpdir(), 'ts-types-')));
+
+  try {
+    await fs.writeFile(path.join(tmpDir, 'package.json'), '{}');
+    await execCommand(
+      process.execPath,
+      [
+        resolve(dirname(createRequire(import.meta.url).resolve('corepack/package.json')), 'dist/pnpm.js'),
+        'install',
+        installCommand.replace(/^npm install /, ''),
+        'typescript',
+      ],
+      {
+        cwd: tmpDir,
+      },
+    );
+
+    const links: [string, string][] = [];
+    const files: [string, string][] = [];
+
+    function* walkSync(dir: string, seen = new Set<string>()): Generator<[string, string]> {
+      for (const file of readdirSync(dir)) {
+        const filepath = path.join(dir, file);
+        const real = realpathSync(filepath);
+        const stats = statSync(real);
+
+        if (real !== path.resolve(filepath)) {
+          links.push(['/' + path.relative(tmpDir, filepath), '/' + path.relative(tmpDir, real)]);
+        }
+
+        if (seen.has(real)) {
+          return;
+        } else {
+          seen.add(real);
+        }
+
+        if (stats.isDirectory()) {
+          yield* walkSync(real, seen);
+        } else if (stats.isFile() && /\.d\.[cm]?ts(\.map)?$|[/\\]package\.json$/.test(filepath)) {
+          const rel = path.relative(tmpDir, path.resolve(filepath));
+          const lib = /^.+\/typescript\/lib\/lib/;
+
+          if (lib.test(rel)) {
+            links.push(['/' + rel.replace(lib, 'lib'), '/' + rel]);
+          }
+
+          yield ['/' + rel, readFileSync(filepath, 'utf-8')];
+        }
+      }
+    }
+
+    const nodeModulesPath = path.join(tmpDir, 'node_modules');
+    for (const file of walkSync(nodeModulesPath)) {
+      files.push(file);
+    }
+
+    const output = JSON.stringify({ files, links });
+    await fs.writeFile(path.join(typesPath, 'typescript.json'), output);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}

package/src/build.ts

@@ -0,0 +1,97 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { buildTypescriptTypes } from './build-ts-types';
+import { buildPythonTypes } from './build-py-types';
+import path from 'node:path';
+import type * as SDKJSON from '@stainless/sdk-json';
+
+export type Auth = Array<{
+  type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+  description?: string;
+  name: string;
+  title: string;
+  header: string | undefined;
+  example: string | undefined;
+  opts: {
+    type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+    nullable: boolean;
+    description?: string | undefined;
+    example?: unknown;
+    default?: unknown;
+    read_env?: string | undefined;
+    auth?:
+      | {
+          security_scheme: string;
+          role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+        }
+      | undefined;
+    name: string;
+  }[];
+}>;
+
+export async function buildPlaygrounds({
+  spec,
+  langs,
+  auth,
+  playPath,
+  reportError,
+}: {
+  spec: SDKJSON.Spec;
+  langs: SDKJSON.SpecLanguage[];
+  auth: Auth;
+  playPath: string;
+  reportError: (message: string) => void;
+}) {
+  const cacheKey = JSON.stringify([
+    1,
+    langs,
+    Object.entries(spec.metadata).map(([k, v]) => [k, v.install, v.version]),
+    auth,
+  ]);
+  const { cachedKey } = await (async () => {
+    await mkdir(playPath, { recursive: true });
+    const cachedKey = await readFile(path.join(playPath, 'cache-key'), 'utf-8').catch(() => {});
+    return { cachedKey };
+  })();
+  if (cacheKey === cachedKey) return;
+
+  let softFail = false;
+  await Promise.all([
+    (async () => {
+      try {
+        const tsInstall = spec.metadata.typescript?.install;
+        if (tsInstall && langs.includes('typescript')) {
+          return await buildTypescriptTypes(playPath, tsInstall);
+        }
+      } catch {
+        reportError('Playgrounds build for TypeScript failed! TypeScript playgrounds will not be available.');
+        softFail = true;
+      }
+      await writeFile(path.join(playPath, 'typescript.json'), 'null');
+    })(),
+    (async () => {
+      try {
+        const pyInstall = spec.metadata.python?.install;
+        if (pyInstall && langs.includes('python')) {
+          return await buildPythonTypes(playPath, pyInstall);
+        }
+      } catch {
+        reportError(
+          'Playgrounds build for Python failed! Python playgrounds will not be available. Do you have python3 and python3-virtualenv installed?',
+        );
+        softFail = true;
+      }
+      await writeFile(path.join(playPath, 'python.json'), 'null');
+      await mkdir(path.join(playPath, 'python'), { recursive: true });
+      await writeFile(path.join(playPath, 'python', 'wheel.whl'), '');
+    })(),
+    writeFile(path.join(playPath, 'auth.json'), JSON.stringify(auth)),
+  ]).then(async () => {
+    if (softFail) {
+      // don't cache failed builds
+      // todo: partial caching
+      await rm(path.join(playPath, 'cache-key')).catch(() => {});
+    } else {
+      await writeFile(path.join(playPath, 'cache-key'), cacheKey, 'utf-8');
+    }
+  });
+}