Skip to content

feat(snippets): add sdk-docs install canonicals for 9 SDKs#439

Open
kinyoklion wants to merge 1 commit into
rlamb/aiconfig-observability-validationfrom
rlamb/sdk-docs-install-canonicals
Open

feat(snippets): add sdk-docs install canonicals for 9 SDKs#439
kinyoklion wants to merge 1 commit into
rlamb/aiconfig-observability-validationfrom
rlamb/sdk-docs-install-canonicals

Conversation

@kinyoklion
Copy link
Copy Markdown
Member

@kinyoklion kinyoklion commented May 8, 2026

Summary

Stacked on #428, which lands the shell-install validator infrastructure (with gem support and the multi-line last_pkg extractor). Adds 12 canonical .snippet.md files for the install / manifest <CodeBlock> regions in ld-docs's top-level reference pages that the original auto-port (#414) skipped per SDK-2300. All 12 get end-to-end shell-install validation against the real package registry.

Unblocks the corresponding marker insertions on ld-docs-private #7592.

Per-SDK file list + validation status

SDK New snippet IDs Validation
node-server-sdk install-the-sdk-shell ✅ shell-install (npm)
node-client-sdk install-the-sdk-installing-with-npm, …with-yarn ✅ shell-install (npm + yarn)
react-native-client-sdk install-the-sdk-installing-react-native-sdk-v10, …adding-the-async-storage-dependency ✅ shell-install (yarn × 2)
ruby-server-sdk install-the-sdk-shell ✅ shell-install (gem)
vue-client-sdk install-the-sdk-installing-with-npm, …with-yarn ✅ shell-install (npm + yarn)
dotnet-server-sdk install-the-sdk-shell ✅ shell-install (dotnet CLI; Install-Package legacy line stripped)
java-server-sdk install-the-sdk-gradle ✅ shell-install (gradle DSL fragment in synthesized build.gradle)
php-server-sdk install-the-sdk-shell ✅ shell-install (composer)
rust-server-sdk install-the-sdk-shell ✅ shell-install (cargo)

go-server-sdk is intentionally not included — the "Shell install" mention in PR #7592's per-SDK table refers to a prose backtick quote of go get …, not an MDX CodeBlock.

Validator extensions (Dockerfile + harness)

The shell-install image grew from a node + python + go + ruby base to also include rust toolchain, php + composer, .NET SDK 8, and OpenJDK 17 + Gradle 8.10. Image is now ~2 GB — a CI-only artifact, cached per matrix cell, so the size pays for itself after the first build.

New harness LEAD cases:

  • cargocargo init in a clean dir, run body, grep Cargo.toml for the package name.
  • php — symlinks /opt/composer.phar into the working dir so the body's literal php composer.phar require … resolves; composer init; run body; check vendor/<pkg>/.
  • dotnetdotnet new console -n InstallSanity, cd in, run body, grep <PackageReference Include="…"> from the generated csproj.
  • Install-Package strip — multi-line bodies that show the legacy NuGet PowerShell Install-Package form alongside the modern dotnet add package CLI form (for backward-compat documentation) get the legacy line stripped before LEAD detection. The dotnet CLI line is then validated via the case above.
  • implementation (Gradle DSL fragment) — synthesizes a minimal build.gradle (plugins { id 'java' }, mavenCentral(), the body inserted in dependencies { … }); runs gradle dependencies; greps the dependency-tree output for the artifact name extracted from the body's name: '…' field.

Bug found + fixed inline

shell-install's last_pkg extractor was picking up trailing inline # comment text as a package name. Multi-line bodies like vue's npm install --save launchdarkly-vue-client-sdk\nnpm install @launchdarkly/observability # optional observability plugin\nnpm install @launchdarkly/session-replay # optional session replay plugin extracted plugin as the last package and then failed assert_node_modules looking for node_modules/plugin/. Fixed by stripping inline shell comments before field-splitting in awk. Benefits any sdk-info or observability install body with comments too.

Body fidelity

Each .snippet.md body is a byte-verbatim copy of what's in ld-docs today. Verified by running snippets render --target=ld-docs after a synthetic marker insertion and confirming the diff is exactly the marker comment — zero body bytes change.

Test plan


Note

Medium Risk
Moderate risk because it expands the shell-install validator’s Docker image/toolchain and adds new command-parsing/execution paths (cargo/composer/dotnet/gradle), which could impact CI reliability and install-snippet validation behavior.

Overview
Adds canonical sdk-docs “Install the SDK” snippet files for 9 SDKs (Node server/client, React Native, Vue, Ruby, Rust, PHP, .NET, Java) and binds them to the shell-install validator.

Expands the shell-install validator image and harness to validate additional install styles: installs Rust/cargo, PHP+Composer, .NET SDK, and JDK+Gradle; adds harness strategies for cargo add, php composer.phar require, dotnet add package, and Gradle implementation ... fragments; strips legacy NuGet Install-Package lines; and fixes package-name extraction to ignore inline # comments in multi-line bodies.

Reviewed by Cursor Bugbot for commit ec8d6b6. Bugbot is set up for automated code reviews on this repo. Configure here.

Adds 12 canonical .snippet.md files under
snippets/sdks/<sdk>/snippets/sdk-docs/ for the install/manifest
CodeBlocks in ld-docs's top-level reference pages
(`fern/topics/sdk/{server-side,client-side}/<sdk>/index.mdx`) that
the original auto-port (sdk-meta PR #414) skipped per the
shell/bash/cmd skip rule (SDK-2300).

These snippets unblock ld-docs-private PR #7592, which can insert
markers pointing at them in a follow-up commit once this lands and
a new `snippets/v*` is cut.

Per-SDK file count:

| SDK | snippet IDs |
|---|---|
| dotnet-server-sdk | install-the-sdk-shell |
| java-server-sdk | install-the-sdk-gradle |
| node-server-sdk | install-the-sdk-shell |
| php-server-sdk | install-the-sdk-shell |
| ruby-server-sdk | install-the-sdk-shell |
| rust-server-sdk | install-the-sdk-shell |
| node-client-sdk | install-the-sdk-installing-with-npm, install-the-sdk-installing-with-yarn |
| react-native-client-sdk | install-the-sdk-installing-react-native-sdk-v10, install-the-sdk-adding-the-async-storage-dependency |
| vue-client-sdk | install-the-sdk-installing-with-npm, install-the-sdk-installing-with-yarn |

`go-server-sdk` is intentionally not in the list: the "Shell install"
mention in PR #7592's per-SDK table refers to a prose backtick quote
of `go get …`, not an MDX CodeBlock — there's nothing to canonicalize.

Bodies are byte-verbatim copies of what's in ld-docs today; verified
by running `snippets render --target=ld-docs` after a synthetic
marker insertion and confirming a zero-body-diff.

No `validation:` block: these are install/manifest fragments, not
runnable units. Adding shell-install or build-system-harness
validation for them is a separate workstream (PR #428's territory).

Replaces the originally-opened-as-9-separate-PRs sequence
(#430-#438) with a single PR per the user's
intent.
@kinyoklion kinyoklion force-pushed the rlamb/sdk-docs-install-canonicals branch from 28d356a to ec8d6b6 Compare May 8, 2026 22:43
@kinyoklion kinyoklion marked this pull request as ready for review May 8, 2026 22:55
@kinyoklion kinyoklion requested a review from a team as a code owner May 8, 2026 22:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant